API reference

Streams

Programmatic control of AI-hosted live streams.

Method	Path	Scope
`POST`	`/api/v1/streams`	`streams:write`
`GET`	`/api/v1/streams`	`streams:read`
`GET`	`/api/v1/streams/{id}`	`streams:read`
`DELETE`	`/api/v1/streams/{id}`	`streams:write`

Stream lifecycle

preparing → live → ended
                 ↘ error

Status	Meaning	Fields populated
`preparing`	Stream created, agent is being dispatched to the room.	`stream_id`, `room_name`, `created_at`
`live`	Avatar is streaming to the platform. Billing starts here.	+ `started_at`, `viewer_count` (live-updating)
`ended`	Stream finished (via `DELETE`, the agent, or the platform). Billing stops.	+ `ended_at`, final `viewer_count`
`error`	Something failed. Inspect `events` on `GET /streams/{id}`.	+ `ended_at`, error `events`

Start a stream

POST /api/v1/streams

Request body

Field	Type	Required	Notes
`creator_id`	string	✅	Creator to host (see your dashboard marketplace).
`product_name`	string	✅	Product/game being featured.
`platform`	string	✅	`youtube`, `tiktok`, `twitch`, `kick`, `facebook`, `instagram`.
`script`	string	–	Talking points / script seed for the host.
`vertical`	string	–	`live-commerce` or `igaming`. Must match your brand's vertical.

Response 201 Created

{
  "stream_id": "a1b2c3d4-e5f6-…",
  "status": "preparing",
  "room_name": "stream-a1b2c3d4",
  "ws_url": "wss://…livekit…",
  "viewer_token": null,
  "created_at": "2026-08-07T10:00:00.000Z"
}

Test keys: with tt_test_… the stream returns status: "live" immediately (plus "test": true, ws_url: null) — no agent dispatch, no billing — so you can build the full lifecycle integration, including DELETE, without a real stream.

Errors: 400 missing_fields · 400 invalid_creator · 401 unauthorized · 402 plan_required · 403 vertical_mismatch · 429 rate_limited · 429 concurrency_limit

List streams

GET /api/v1/streams?status=live&limit=20&offset=0

Param	Default	Notes
`status`	all	Filter: `preparing`, `live`, `ended`, `error`.
`limit`	20	Max 100.
`offset`	0	For pagination.

Response 200

{
  "streams": [ { "id": "…", "status": "live", "platform": "youtube", … } ],
  "total": 47,
  "limit": 20,
  "offset": 0
}

Results are newest-first and scoped to your brand.

Get a stream

GET /api/v1/streams/{id}

Response 200

{
  "stream_id": "a1b2c3d4-…",
  "status": "live",
  "creator_id": "mila",
  "product_name": "Radiance Serum",
  "platform": "youtube",
  "vertical": "live-commerce",
  "viewer_count": 312,
  "started_at": "2026-08-07T10:00:14.000Z",
  "ended_at": null,
  "room_name": "stream-a1b2c3d4",
  "events": [
    { "type": "stream.started", "created_at": "…" },
    { "type": "stream.first_purchase", "created_at": "…" }
  ]
}

404 if the stream doesn't exist or belongs to another brand.

End a stream

DELETE /api/v1/streams/{id}

Ends a live stream immediately and stops billing.

Response 200

{ "stream_id": "a1b2c3d4-…", "status": "ended", "ended_at": "2026-08-07T11:30:00.000Z" }

404 if the stream isn't found or isn't live.

← Previous

iGaming guide

Analytics

Was this page helpful?