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

Preparing streams that can't dispatch within 5 minutes automatically transition
to error. `preparing` time never consumes plan minutes.

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 during dispatch or streaming. See the `status` field for details.	+ `ended_at`

Stuck preparing: if the agent worker can't join within 5 minutes, the stream transitions to error and a stream.error webhook fires (if registered). preparing time never consumes plan minutes.

Start a stream

POST /api/v1/streams

Request body

Field	Type	Required	Notes
`creator_id`	string	✅	Creator to host (use `GET /api/v1/creators` to list available creators).
`product_name`	string	✅	Product/game being featured.
`platform`	string	✅	`youtube`, `tiktok`, `twitch`, `kick`, `facebook`, `instagram`. iGaming brands: see the iGaming guide — not all platforms are available to you.
`duration_minutes`	number	✅ live / – test	How long to stream (1–480 minutes). Required for live keys. Omit with test keys — they return `live` immediately.
`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-…",    // ← save this — you'll need it to poll/end
  "status": "preparing",
  "room_name": "stream-a1b2c3d4",
  "ws_url": "wss://rt.twintone.ai/v1/rooms/stream-a1b2c3d4",
  "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 minutes consumed — so you can build the full lifecycle integration, including DELETE, without a real stream.

Errors: 400 missing_fields · 400 invalid_fields · 400 invalid_creator · 401 unauthorized · 402 plan_required · 402 no_minutes · 402 insufficient_credits · 403 vertical_mismatch · 429 rate_limited · 429 concurrency_limit · 502 launch_failed

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": "avt_9ww075quzedr",              // ← the creator you picked
  "product_name": "Radiance Serum",  // ← YOUR product name
  "platform": "youtube",
  "vertical": "live-commerce",
  "viewer_count": 312,
  "started_at": "2026-08-07T10:00:14.000Z",
  "ended_at": null,
  "room_name": "stream-a1b2c3d4",
  "events": []
}

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

Note: the events field is currently empty (reserved for future telemetry events).

End a stream

DELETE /api/v1/streams/{id}

Ends a live stream immediately.

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

Creators

Analytics

Was this page helpful?