Resources

Changelog

All notable changes to the TwinTone API (v1) are documented here. Entries are dated and grouped by Added / Changed / Fixed.

2026-10-24

Changed

• A test key only sees and ends test-key streams. GET /streams, GET /streams/{id}, DELETE /streams/{id} and GET /analytics with a tt_test_ key now reach only streams started with a test key. Your real streams are left out of its lists and analytics, and reading or ending one returns 404 not_found. Before, a test key could read the brand's real streams and end them, which stopped the broadcast. The MCP tools follow the same rule. Live keys are unchanged.

Fixed

• The MCP tools and these docs now describe billing the way streams are counted. start_stream described a separate per-minute charge, and end_stream and DELETE /streams/{id} said ending a stream stops billing. API streams use your plan's streaming minutes, and a live-key stream counts the full duration_minutes it booked once it is live, so ending it early does not give minutes back. Test-key streams use no minutes. Billing itself has not changed.

2026-10-23

Added

• warnings on stream start. A live-key POST /streams for a brand with no connected channel that has a stream key still starts, but the 201 response now includes a no_broadcast_destination warning: the stream reaches no platform until a channel is connected.

Changed

• Test keys are free. Any account with a confirmed email can create a tt_test_ key in the dashboard, with no plan. Live keys still need the Growth plan or above (402 plan_required).
• Test-key streams have their own concurrency limit. Up to 3 per brand, counted separately from live streams, and each ends on its own after 30 minutes.
• Webhook limits. At most 10 active webhooks per brand (409 webhook_limit), and up to 1,000 waiting deliveries per brand. Delivery now takes turns across brands, so one brand's backlog can no longer hold up other brands' events.
• GET /creators rejects an invalid key. Sending no key still returns the public list. Sending an Authorization header that doesn't validate now returns 401 unauthorized instead of the public list, so a mistyped key is caught on the first call.

2026-10-12

Added

• MCP server — POST /api/mcp is now a working remote MCP server over the Streamable HTTP transport (JSON responses, stateless). It exposes five tools that wrap the v1 REST endpoints: list_creators, list_streams, get_stream (Read) and start_stream (billable sensitive write), end_stream (destructive write). Both write tools require confirm: true. See MCP server.

Changed

• API streams use plan minutes only. A leftover balance check could reject a live stream with 402 insufficient_credits even though API streams have never been charged to a credit balance. That check is removed; insufficient_credits is no longer returned by POST /streams.
• Pricing page now lists the plans that include API access and explains how minutes are counted: a live stream counts its booked duration_minutes once it goes live.

Fixed

• 402 no_minutes is documented. It is returned when your plan's minutes for the billing period are used up (the 2026-09-12 entry said it didn't exist; it does).
• Docs said test keys need no plan. Creating any key, test or live, needs the Growth plan or above.
• kick removed from the documented platform values; it isn't available to live-commerce brands (403 vertical_mismatch).
• DELETE /streams/{id} now stops the broadcast. Before, it only marked the stream ended; on a live key the broadcast kept running on the platform until its booked duration ran out. It now stops the broadcast first. If that can't be confirmed it returns 502 stop_failed and the stream stays live, so you can retry.
• Live-key starts fire stream.started. Only test keys sent it before.
• POST /streams returns the real status. Live keys returned preparing while the stream was already live; the response now matches.

2026-09-12

Changed

• API keys moved in the dashboard — they now live under the sidebar DEVELOPERS → API Keys section (with Usage and Docs), no longer under Billing or Settings. All docs cross-references updated. API Keys and Webhooks also appear as tabs of the dedicated /dashboard/api hub.
• Pricing page rewritten — API streams draw on the same plan minutes as dashboard streams; the previous per-minute tier table and credit-wallet model never shipped and is removed. Live keys still require the Growth plan or above (402 plan_required); test keys remain free.

Fixed

• Error reference no longer lists insufficient_credits / no_minutes — neither code exists in the API; the only 402 is plan_required.

2026-09-04

Fixed

• The OpenAPI spec is now downloadable directly from the docs site (/openapi.yaml) — the spec was previously only reachable via a private GitHub link.
• Rate-limit docs no longer promise a Retry-After header the API doesn't send.
• Clarified that crypto in the webhook signature examples is Node's standard hashing library (not cryptocurrency), and corrected the webhook testing notes.

2026-08-07

v1 — initial release

The TwinTone API launches in early access. Endpoints are stable but the surface area is intentionally small; webhook event taxonomies are versioned so additions never break existing integrations.

Added

• Streams — programmatic control of AI-hosted live streams:
  • POST /api/v1/streams — start a stream (agent dispatch, lifecycle preparing → live → ended | error).
  • GET /api/v1/streams — list your brand's streams with status / limit / offset filters.
  • GET /api/v1/streams/{id} — full stream detail including event history.
  • DELETE /api/v1/streams/{id} — end a live stream.
• Analytics — GET /api/v1/analytics with period (24h / 7d / 30d) and per-stream filters; platform breakdown and per-stream rows included.
• Webhooks — POST / GET / DELETE /api/v1/webhooks with stream.started, stream.ended, and stream.error events, HMAC-SHA256 signature verification (X-TwinTone-Signature), 5-minute replay window, and up to 5 retries with exponential backoff.
• Scoped API keys — tt_live_… / tt_test_… keys with least-privilege scopes (streams:read, streams:write, analytics:read, webhooks:write), created in the dashboard's DEVELOPERS → API Keys section.
• Test mode — tt_test_ keys simulate the full request/response lifecycle with no agent dispatch and no billing, so integrations can be built and verified for free.
• Unified error envelope — every error returns { "error": { "code", "message" } } with stable codes (missing_fields, invalid_fields, invalid_creator, unauthorized, insufficient_scope, vertical_mismatch, not_found, rate_limited, concurrency_limit, db_error, launch_failed).
• Brand vertical locking — a stream's vertical must match the brand's configured vertical, otherwise the request fails with vertical_mismatch.

Changed

• Nothing — this is the initial release.

Fixed

• Nothing — this is the initial release.

Documentation is versioned with the API. Check this page for updates, or see API pricing and Errors & rate limits for the current contract.