HTTP API Reference

Call MediaSFU from your server with no SDK. Every resource below uses the same base URL, authentication and response format.

Authentication

Authorization: Bearer <api-username>:<api-key>

Find both values under API keys. Send requests from your server only; never ship the key in a browser or mobile app. For short-lived, scoped access, use disposable keys.

Actions are selected with an action field: in the JSON body for POST, and in the query string for GET.

Resources

Resource	Endpoint	What it does
Rooms / Sessions	/v1/rooms	Everything on MediaSFU runs inside a room — meetings, calls and AI agents all start here.
Event settings	/v1/eventssettings	Account-level defaults applied to new rooms — what participants may do, plus AI-notes wiring.
Recording settings	/v1/recordingsettings	Account-level recording defaults applied when rooms record.
Recordings	/v1/recordings	List and fetch your recorded session files.
Account balance	/v1/balance	Read remaining sandbox and production meeting and recording minutes.
Sub-users	/v1/subusers	Team members that share your main account and billing. Parent-role sub-users can manage some of their own settings.
Allowed domains	/v1/domains	Domains authorised to send create/join requests with your production API key. Required for any domain proxying those requests — embedding is irrelevant.
Disposable API keys	/v1/disposable-keys	Short-lived keys for embedding widgets or one-off integrations. The full value is shown only once on create.
AI credentials	/v1/aicredentials	Your own AI provider keys (STT, LLM, TTS, realtime). Only needed if you are not using MediaSFU-managed AI.
SIP configuration	/v1/sipconfigs	Bring your own number so an agent can answer or place calls. MediaSFU-provided numbers are for outgoing non-AI calls only.
Translation config	/v1/translationconfigs	Named AI-notes / translation presets, wiring together your STT, LLM and TTS credentials.

Streaming (WHIP, WHEP and HLS) and AI call control have their own guides: Streaming and AI call control.

Responses and errors

Every /v1 response is JSON. Success and failure share one shape, so a single handler covers both.

Success. HTTP 2xx. success is always true; the payload sits alongside it under a resource-named key.

{
  "success": true,
  "rooms": [
    "…"
  ],
  "total": 2,
  "startIndex": 0,
  "pageSize": 20
}

Failure. success is false, error is a message safe to show a user, and code is stable — branch on code, not on the text.

{
  "success": false,
  "error": "Room not found.",
  "code": "NOT_FOUND"
}

Code	HTTP status	Meaning
BAD_REQUEST	400	The request was malformed or failed validation.
UNAUTHORIZED	401	Missing or unusable credentials.
FORBIDDEN	403	Authenticated, but not allowed to do this.
NOT_FOUND	404	No such record, or it is outside your account.
CONFLICT	409	Clashes with current state — e.g. the name is taken.
RATE_LIMITED	429	Too many requests. Back off and retry.
INTERNAL_ERROR	500	A fault on our side. Safe to retry.

Error messages never contain internal detail — no database identifiers, field paths or stack text. When something fails internally you get a generic message and the specifics stay in our logs.

Endpoints that return a plain array

These return a plain JSON array today. Add ?envelope=1 (or the header X-MediaSFU-Response: envelope) to get the standard { success, data } shape instead. The array default will remain until every known caller has moved.

• GET /v1/room/logs: Room usage logs, record usage logs and messages.
• GET /v1/sipcall/logs: Call transcripts, summaries and callback state.

Try any request live in the API Sandbox.