Skip to content
TipPage Docs
Esc
↑↓navigate↵open⌘Jpreview

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. Refused with 409 queue_paused while the media queue is paused. Unlike the TTS claim there is no already-playing gate: 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_... or tpat_...) · headerrequired

A TipPage API key (tp_live_..., created in Dashboard → Settings → Developer) or an OAuth 2.0 access token (tpat_..., see the OAuth guide). Both carry the same scopes and are accepted on every endpoint.

Path parameters
orderIdstringrequired

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

Responses
200

Claimed.

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>
401

Missing or invalid credential (missing_api_key / invalid_api_key, or invalid_token for an expired/revoked OAuth access token).

errorstringrequired

Human-readable message.

codestring

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

403

The key lacks the required scope (missing_scope).

errorstringrequired

Human-readable message.

codestring

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

required_scopestring
404

No such resource.

errorstringrequired

Human-readable message.

codestring

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

409

queue_paused - the media queue is paused.

errorstringrequired

Human-readable message.

codestring

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

429

Rate limit exceeded - check the RateLimit-* headers.

errorstring
Try it
Server
Authorization
Parameters
Request
curl -X POST 'https://api.tippage.com/v1/media/string/start' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'
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"
  }
}