Meetings and Calls API

Meetings are created as meeting rooms through the Chat API. This page documents the media and guest-access APIs used after a meeting room exists.

Unless a route is marked Public invite route, send a Ration bearer token:

Authorization: Bearer <ration_access_token>
Accept: application/json

Meeting and call capabilities require the Collaboration feature for the caller's tenant.

Create or retrieve the media room

POST /apis/v1/call/rooms

{ "chat_room_id": "meeting-room-id" }

Request field	Type	Required	Description
chat_room_id	String	Yes	Existing Ration chat/meeting room ID.

The endpoint creates or reuses the media room associated with the meeting. It returns room_id and a transport payload:

Response field	Type	Description
room_id	String	Media-room identifier; retain it for token minting.
transport	String	ration_realtime for Ration's current managed media transport.
media	Object	Media credentials described below.
media.endpoint	String	Media endpoint.
media.access_token	String	Short-lived media access credential.
media.ice_servers	Array	STUN/TURN relay configuration.

Mint a meeting token

GET|POST /apis/v1/call/tokens/:room_id/mint

The caller must be authorized to join the call. The server determines the role and media permissions from the meeting and caller; do not attempt to supply these in the request.

Name	In	Type	Required	Description
room_id	Path	String	Yes	Media room ID returned by POST /call/rooms.
hd_video, hd	Query or body	Boolean	No	Request HD video when the tenant is entitled; otherwise the response uses sd.
video_quality	Query or body	String	No	hd, high, true, or 1 also request HD video.

Media transport response

Field	Type	Description
room_id	String	Media room ID.
transport	String	ration_realtime.
protocol	String	Control-channel protocol (call.v1).
control_token	String	Credential for the meeting control channel.
media.endpoint	String	Media endpoint.
media.access_token	String	Short-lived media access credential.
media.ice_servers	Array	STUN/TURN server configuration.
media.video_profile	String	sd by default, or hd when explicitly requested and entitled.

For Ration's control-channel transport, the response has room_id, transport, protocol, and control_token.

Errors: 401 unauthorized means user context is missing; 403 call_not_ready means the caller cannot join; 409 room_full means the participant limit was reached; 500 token_mint_failed means credentials could not be generated.

Meeting status and recordings

List currently-live meetings

GET /apis/v1/meetings/live

Response: { "live": { "<chat_room_id>": <participant_count> } }. A room not present in live is not currently active.

List recordings for a meeting

GET /apis/v1/chat/rooms/:id/recordings

The caller must belong to the room.

Response field	Type	Description
recordings	Array	Recording metadata.
recordings[].recording_id	String	Recording identifier.
recordings[].status	String	Current lifecycle status.
recordings[].started_at, completed_at	String or null	Lifecycle timestamps.
recordings[].duration_seconds, size_bytes	Number or null	Duration and size when known.
recordings[].available	Boolean	true only after the recording is finalized and available.

List the caller's meeting recordings

GET /apis/v1/meetings/recordings

Returns { "recordings": [...] } across meeting rooms visible to the caller. Each entry includes recording_id, room_id, meeting_name, status, started_at, duration_seconds, and available.

Authenticated external-invite administration

The following routes create and administer guest access. Supply either meeting context (chat_room_id) or call context (call_id) as required by the operation.

Method	Path	Request	Response
POST	/apis/v1/call/external_invites	Guest details plus chat_room_id or call_id.	Invite with invite_url and invite_token.
POST	/apis/v1/chat/rooms/:id/external_invites	Guest details for that room.	Invite with invite_url and invite_token.
GET	/apis/v1/chat/rooms/:id/external_invites/chat_link	Optional external_party_id, reinitiate.	Existing/reinitiated guest link.
GET	/apis/v1/chat/rooms/:id/external_invites/approvals	—	{ "requests": [...] }.
POST	/apis/v1/chat/rooms/:id/external_invites/approvals/:request_id	action (or decision), optional reason, revoke.	{ "request": {...} }.
POST	/apis/v1/chat/rooms/:id/external_invites/domain_request	guest_email (or email).	{ "domain": "…", "status": "…" }.
POST	/apis/v1/call/:call_id/external/lock	Required locked Boolean.	{ "call_id": "…", "locked": Boolean }.
POST	/apis/v1/call/:call_id/external/participants/:guest_id/remove	Optional reason.	{ "call_id": "…", "guest_id": "…", "removed": true }.

Invite creation accepts guest identity fields such as guest_email, email, guest_name, and name; the returned invite_url is the link to share. It may also send the invitation email when a guest email is provided. The creator/member and room-type policy is enforced server-side.

Public invite routes

These routes do not use a Ration bearer token. Their unguessable invite_token, short-lived session credentials, OTP verification, rate limits, and server-side room policy control access. Do not expose any returned session or media token in logs.

Inspect and verify an invite

Method	Path	Request	Successful response
GET	/apis/v1/call/external/:invite_token/status	—	Current safe invite status.
POST	/:invite_token/otp	—	{ "status": "sent", "masked_email": "…", "expires_at": "…" }.
POST	/:invite_token/claim	display_name/name; OTP as verification_code, verificationCode, otp, or code.	Guest claim/session data.
POST	/:invite_token/call_session	Guest chat token, optional OTP field and call_id; optional step_up.	Call-session data.

All abbreviated paths in this table are relative to /apis/v1/call/external. OTP and claim attempts are rate-limited. Common responses include 403 invite_expired, invite_revoked, otp_required, or approval_required; 429 signals rate limiting.

Mint a guest media session

POST /apis/v1/call/external/session/mint

{ "session_token": "guest-session-token" }

Response:

Field	Type	Description
transport	String	ration_realtime.
media.endpoint, media.access_token	String	Guest media credentials.
media.ice_servers	Array	STUN/TURN configuration.
media.video_profile	String	Selected media profile.
room_name, guest_id, call_id	String	Guest call context.

Public livestream guests

POST /apis/v1/call/external/:invite_token/livestream_join

{ "display_name": "Guest", "email": "guest@example.com" }

display_name (or name) is required. Successful responses return receive-only media credentials, room_name, guest_id, call_id, leave_token, session_token, and chat_room_id.

To unlock livestream chat and ask-to-speak, request an emailed OTP then verify it:

1. POST /:invite_token/livestream_verify/request with session_token.
2. POST /:invite_token/livestream_verify with session_token and code (or otp).

The verification response contains { "status": "verified", "chat_token": "…", "chat_room_id": "…", "guest_id": "…", "guest_name": "…" }.

Finally, POST /apis/v1/call/external/session/leave with leave_token and optional reason records guest departure and returns { "status": "ok" }.

Error guide

Status	Meaning
401	Authenticated meeting route has no valid caller context.
403	Caller/guest is not allowed, the call is not ready, an invite is expired/revoked, or an approval/step-up check is required.
404	Call, room, guest, invite, or approval request was not found.
409	Call capacity was reached or an approval was already decided.
422	Missing/invalid fields or an operation cannot be applied to the current call/room state.
429	OTP, claim, or session-mint rate limit reached.