Keepalive

Renews the stream lease and returns a fresh publish token. Clients should renew before the 5-minute lease expires, for example every 4 minutes, and pass the returned token to the LiveKit SDK with room.updateToken(...).

POST /streams/{stream_id}/keepalive

Renew stream lease

cURL

curl --request POST \
  --url https://api.overshoot.ai/v1beta/streams/{stream_id}/keepalive \
  --header 'Authorization: Bearer <token>'

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "expires_at_ms": 123,
  "ttl_seconds": 300,
  "publish": {
    "type": "livekit",
    "url": "<string>",
    "token": "<string>"
  },
  "stream_time_ms": 123
}

When to call

Streams expire 5 minutes after the last keepalive (or creation, if no keepalive has happened yet). Call /keepalive every ~2 minutes — clock skew is real and the cost of a missed renewal is the whole stream.

A keepalive on a stream that’s already ended returns 404. Streams cannot be revived; create a new one.

What you get back

Every successful keepalive returns:

• A new expires_at_ms set to now + ttl_seconds.
• A fresh LiveKit publish.token. Save it — if your publisher disconnects from the room, you’ll need a current token to rejoin without recreating the stream. Old tokens may stop working.
• The current stream_time_ms (matches GET /streams/{id}).

Authorizations

Authorization · string · header · required

Every public HTTP request requires Authorization: Bearer <api_key>, except GET /models and the public /billing/pricing endpoints.

• 401 means the key is missing, unknown, or revoked.
• 403 means the key is valid but cannot access the requested resource.
• The publish token returned by POST /streams is only for publishing media to LiveKit. It does not replace the API key for HTTP calls.

Headers

X-Overshoot-Region · enum<string>

Optional hint to route the request to the region that owns the stream. If the request reaches the wrong region the API returns 409 with a region_error body.

Available options: us-west1, us-central1

Path Parameters

stream_id · string<uuid> · required

UUID returned by POST /streams.

Response

200

application/json

Lease renewed.

id · string<uuid> · required

expires_at_ms · integer · required

ttl_seconds · integer · required

Example:

300

publish · object · required

WebRTC publish target. Connect with the LiveKit client SDK.

Show child attributes

stream_time_ms · number

Current stream-clock position in ms.