Playback heartbeat

POST/v1/playback/sessions/{sid}/heartbeat

Sent by the player every heartbeatIntervalSeconds. Marks the session live and rotates the watermark token. Auth: the videohati-session-token header. Rate limit: 10 requests per 60 s per session.

A heartbeat that ends the session (the delivery gate revokes it) may drain its close in the foreground; if that budget is exhausted the close finishes in the background and the heartbeat returns 503 session_close_retryable.

Error codes: session_invalid (403), session_expired (403), session_revoked_concurrent_cap (403), invalid_body (400), session_close_retryable (503).

Authentication

playbackSessionToken — Playback session ownership token (<sessionId>.<expiryUnix>.<mac>) returned by POST /v1/playback/sessions.

Parameters

Name	In	Type	Required	Description
`sid`	path	string (Ulid)	Yes	Playback session id.

Request body

required

Content type: application/json

Schema: HeartbeatRequest

{
  "nonce": "5f1c9d2a",
  "positionSeconds": 42.5
}

Responses

Status	Meaning
`200`	Heartbeat accepted; fresh watermark token issued.
`400`	The request body or query failed validation. The per-operation description lists the exact `error.code` values.
`403`	The credential is valid but does not permit this action. The per-operation description lists the exact `error.code` values.
`429`	Rate limit exceeded.
`503`	The session close is finishing in the background; retry after the `Retry-After` interval. The retry is idempotent and returns `204` once the close is durable.

Example request

{
  "nonce": "5f1c9d2a",
  "positionSeconds": 42.5
}