Control API

Everything a tenant's backend does with Talkline; nothing its clients do.

Base URL: your deployment's API address — https://api.talkline.example in these pages. Every path below starts /v1.

A tenant's clients speak the wire protocol, through the SDKs; everything here is for its backend.

Authentication. Every route needs a credential; nothing here is public. A tenant's backend sends Authorization: Bearer <api_key>.<api_secret>. The routes under /v1/applications take the platform operator's credential instead, and GET /v1/ice-servers takes a client's access token.

Lists are { "data": [...], "nextCursor": "…" | null } and take limit (1–100, default 20) and cursor. A cursor is opaque; one this API did not issue is 400 validation_failed.

Identifiers are public sids — RM_ rooms, PT_ participants, TR_ tracks, CS_ calls, RC_ recordings — and never the internal keys behind them. Times are ISO 8601 in UTC.

Errors are RFC 9457 problem documents with a machine-readable code. Branch on code, never on title or detail: detail is for a log, and no text here is meant for a user.

Rate limits are per credential, in fixed one-minute windows, and every authenticated response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Each operation names its bucket in x-talkline-rate-limit: read (600 a minute), write (120), calls (60, POST /v1/calls alone) and ice (20, per identity).

Webhooks are described in this document's webhooks section: one envelope for every event, signed with the endpoint's secret.

Compatibility. Within /v1 every change is an addition: no route, field, enum value, error code or webhook event is removed, and none changes meaning. Ignore a field you do not know, and treat an enum value, code or event you do not know as "other". A change that cannot be made so is /v2, served alongside /v1 for at least twelve months after it ships.

Sections

• Rooms — Rooms, the participants in them, and acting on a live one.
• Calls — Calls placed from the server, their history and timelines.
• Recordings — Recording a room, and the files a recording leaves.
• Presence — Who is online or in a call. Signaling's, read here.
• Queues — Routing a call to whichever member is free, and why it chose whom it did.
• Usage — What was used, what a credit buys, and the credit ledgers of the identities a tenant enforces.
• Identities — What a person chose — display name, availability — and where to ring them.
• Webhooks — Where Talkline sends what it knows, and what it sent.
• Tokens — Minting and checking access tokens on the server, for tenants that would rather not mint locally.
• ICE servers — STUN and TURN, for a client holding an access token.
• Health — Whether the API reaches what it depends on.
• Applications — The platform operator's routes. A tenant cannot create tenants.

The document itself

These pages are generated from the OpenAPI 3.1.1 document the server is tested against. Download it to generate a client in a language without an SDK: openapi.yaml.