Skip to content

API reference

Base URL: https://tele-api.cloudguys.io. Bodies are JSON. Browsers may call the API from any origin (CORS); authentication is always the Authorization header, never cookies. Timestamps are RFC 3339; Tele returns UTC or an offset, and accepts either. Unknown body fields are rejected with 400.

Auth column: U = user token, S = service token, Host = user token of the call's host, Member = user token of a call member, Admin = service token from an admin key.

Calls

Method Path Auth Description
POST /v1/calls U, S Create a call (U: the token's user is the host; S: host is required)
GET /v1/calls U, S List calls (U: calls you're a member of)
GET /v1/calls/{id} Member, S Get a call with its members
PATCH /v1/calls/{id} Host, S Edit a call
DELETE /v1/calls/{id} Host, S Cancel (disconnects anyone in the call)
POST /v1/calls/{id}/end Host, S End now (disconnects everyone)
PUT /v1/calls/{id}/members/{user_id} Host, S Add or update a member
DELETE /v1/calls/{id}/members/{user_id} Host, S Remove a member (not the host)
GET /v1/calls/{id}/sessions Host, S Sessions, participants, IPs, durations, charges

POST /v1/calls

Field Type Default Notes
title string required ≤200 characters
access_policy string listed_only or any_client_user
scheduled_start time none omit for an instant call
scheduled_end time none requires scheduled_start; must be in the future
join_opens_before_minutes int 10 0–1440
join_closes_after_minutes int 30 0–1440
max_participants int 10 2–10
max_duration_minutes int 240 1–720, counted from the first join
record bool false
host {user_id, name?, team?} required with a service token; with a user token it must be omitted or match sub
members [{user_id, name?, team?}] [] added as participants
invite {label?, expires_at?, max_uses?} {} options for the default invite

Returns 201 with the call, members, and invite (including the one-time code, and url if your key has an invite URL template).

Call object

{
  "id": "uuid", "title": "string", "status": "scheduled | live | ended | cancelled",
  "access_policy": "listed_only | any_client_user", "host_user_id": "your user id",
  "scheduled_start": "time|null", "scheduled_end": "time|null",
  "join_opens_at": "time|null", "join_closes_at": "time|null",
  "join_opens_before_minutes": 10, "join_closes_after_minutes": 30,
  "max_participants": 10, "max_duration_minutes": 240, "record": false,
  "created_at": "time", "cancelled_at": "time?", "ended_at": "time?",
  "members": [{ "user_id": "…", "name": "…", "role": "host | participant", "added_at": "time" }]
}

GET /v1/calls

Query: status (comma-separated), from, to (RFC 3339, matched on scheduled start or creation time), limit (default 50, maximum 200; larger values are a 400). Returns { "calls": [...] }, newest first.

PATCH /v1/calls/{id}

Any of title, access_policy, scheduled_start, scheduled_end, max_participants, record. Returns 409 call_closed for ended or cancelled calls.

Invites

Method Path Auth Description
POST /v1/calls/{id}/invites Host, S Create {label?, expires_at?, max_uses?}. Returns 201 with the one-time code
GET /v1/calls/{id}/invites Host, S List invites (without codes)
DELETE /v1/invites/{invite_id} Host, S Revoke
GET /v1/invites/{code} U, S Preview: call summary, can_join_now, reason

Joining

Method Path Auth Description
POST /v1/invites/{code}/join U, S Join through an invite. S requires {"user": {"user_id", "ip", "name?", "team?", "user_agent?"}}
POST /v1/calls/{id}/join Member, S Join directly. S requires {"user": {"user_id", "ip", "name?", "team?", "user_agent?"}}

Header: X-Client-Platform (optional, ≤32 characters). Response: Joining a call.

Chat

Method Path Auth Description
GET /v1/calls/{id}/messages Member, S ?after=<message id>&limit= (default 200, maximum 500; larger values are a 400)
POST /v1/calls/{id}/messages Member {stream_id, body, sent_at?}. 201 if new, 200 if already recorded

Recordings

Method Path Auth Description
POST /v1/calls/{id}/recording/start Host, S Start recording a live call (202)
POST /v1/calls/{id}/recording/stop Host, S Stop recording (202)
GET /v1/calls/{id}/recordings Host, S List recordings with their state
GET /v1/recordings/{id} Host, S One recording
GET /v1/recordings/{id}/download Host, S Stream the MP4 (supports Range)
POST /v1/recordings/{id}/restore Host, S Thaw an archived recording

See Recording.

Webhooks

Service tokens only. See Webhooks.

Method Path Auth Description
POST /v1/webhooks S {url, events, description?}. Returns the secret once
GET /v1/webhooks, /v1/webhooks/{id} S List or read endpoints
PATCH /v1/webhooks/{id} S {url?, events?, description?, enabled?}
DELETE /v1/webhooks/{id} S Remove an endpoint
POST /v1/webhooks/{id}/rotate-secret S New secret, 24 h overlap
POST /v1/webhooks/{id}/test S Queue a webhook.test event
GET /v1/webhooks/{id}/deliveries S Delivery log, ?status=&limit=
POST /v1/webhook-deliveries/{id}/retry S Re-send a delivery

An admin key can manage another key's webhooks by adding the header Tele-Client: <key id> to any of these requests. A platform uses it to run its own tenants' endpoints without holding their secrets. The header is ignored on every other route and refused for keys that aren't admin keys.

API keys for your tenants

For platforms that give each of their customers a Tele API key. Admin keys only; the keys made here are never admin keys. Secrets are returned once, at creation and rotation.

Method Path Auth Description
POST /v1/clients Admin {name, owner_ref, invite_url_template?}. owner_ref is your id for the tenant. Returns api_key and api_secret
GET /v1/clients Admin ?owner_ref= (required): that tenant's keys, revoked ones too
DELETE /v1/clients/{id} Admin Revoke. Refused at once; calls and usage stay
POST /v1/clients/{id}/rotate-secret Admin New secret; the old one stops working at once

Usage & rates

Method Path Auth Description
GET /v1/usage S from, to, group_by, team, format=csv. Admins can add api_key
GET /v1/rates Admin ?active=true for rates in effect now
POST /v1/rates Admin Set a rate for a scope (closes the current one)
PATCH /v1/rates/{id} Admin {effective_to?}: end a consumer or team override

Other

Method Path Auth Description
GET /v1/me U, S Who the token represents
GET /healthz, /readyz none Liveness and readiness