Claim a media item as now playing

Marks a queued media item as currently playing - the same call the overlay makes when it starts a video. Fires queue.media.started and sets the timing anchor that /media/now reads. Unlike the TTS claim, there is no pause or already-playing gate (mirroring the overlay protocol): pacing is the consumer’s job. If your player then fails and the item should not count as played, undo the claim with release instead of finishing. See claim, do your thing, finish. Requires media:control.

POST/media/{orderId}/start

Authorization

AuthorizationBearer token (tp_live_...) · headerrequired

A TipPage API key, created in Dashboard → Settings → Developer.

Path parameters

orderIdstringrequired

The media item's order id - the only external row reference.

Responses

200Claimed.

successboolean

mediaQueueMediaItem

A media item in the pending queue.

Show properties

order_idstring

donor_namestring

media_urlstring<uri>

media_start_timeinteger

Start offset in seconds.

video_titlestring | null

video_thumbnailstring<uri> | null

video_durationinteger

Duration in seconds (0 = unknown).

platformstring

requested_viastring

tip | chat | admin | channel_point | ...

is_replayboolean

queued_atstring<date-time>

401Missing or invalid API key (`missing_api_key` / `invalid_api_key`).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. `missing_scope`, `not_in_queue`).

403The key lacks the required scope (`missing_scope`).

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. `missing_scope`, `not_in_queue`).

required_scopestring

404No such resource.

errorstringrequired

Human-readable message.

codestring

Machine-readable code (e.g. `missing_scope`, `not_in_queue`).

429Rate limit exceeded - check the `RateLimit-*` headers.

errorstring

Request

curl -X POST "https://api.tippage.com/v1/media/string/start" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.tippage.com/v1/media/string/start", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.post(
    "https://api.tippage.com/v1/media/string/start",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "success": true,
  "media": {
    "order_id": "string",
    "donor_name": "string",
    "media_url": "http://example.com",
    "media_start_time": 0,
    "video_title": "string",
    "video_thumbnail": "http://example.com",
    "video_duration": 0,
    "platform": "youtube",
    "requested_via": "string",
    "is_replay": true,
    "queued_at": "2019-08-24T14:15:22Z"
  }
}