Skip to main content

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​

ResourceEndpointWhat it does
Rooms / Sessions/v1/roomsEverything on MediaSFU runs inside a room — meetings, calls and AI agents all start here.
Event settings/v1/eventssettingsAccount-level defaults applied to new rooms — what participants may do, plus AI-notes wiring.
Recording settings/v1/recordingsettingsAccount-level recording defaults applied when rooms record.
Recordings/v1/recordingsList and fetch your recorded session files.
Account balance/v1/balanceRead remaining sandbox and production meeting and recording minutes.
Sub-users/v1/subusersTeam members that share your main account and billing. Parent-role sub-users can manage some of their own settings.
Allowed domains/v1/domainsDomains 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-keysShort-lived keys for embedding widgets or one-off integrations. The full value is shown only once on create.
AI credentials/v1/aicredentialsYour own AI provider keys (STT, LLM, TTS, realtime). Only needed if you are not using MediaSFU-managed AI.
SIP configuration/v1/sipconfigsBring your own number so an agent can answer or place calls. MediaSFU-provided numbers are for outgoing non-AI calls only.
Translation config/v1/translationconfigsNamed 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. On list calls, total counts the items in the page you got back and totalCount counts every match across all pages (null when the count is unavailable).

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

Failure. success is false, error is a message safe to show a user, and code is stable, so branch on code rather than the text. Some routes add a message; many failures carry a requestId to quote to support.

{
"success": false,
"error": "Invalid credentials",
"code": "UNAUTHORIZED"
}
CodeHTTP statusMeaning
BAD_REQUEST400The request was malformed or failed validation.
UNAUTHORIZED401Missing or unusable credentials.
FORBIDDEN403Authenticated, but not allowed to do this.
NOT_FOUND404No such record, or it is outside your account.
CONFLICT409Clashes with current state — e.g. the name is taken.
PAYLOAD_TOO_LARGE413The body is bigger than this endpoint accepts.
UNSUPPORTED_MEDIA_TYPE415Send JSON with Content-Type: application/json.
UNPROCESSABLE422Well-formed, but the values cannot be applied.
RATE_LIMITED429Too many requests. Wait for the Retry-After header, then retry.
INTERNAL_ERROR500A fault on our side. Retry GETs; retry a room create or join with the same Idempotency-Key.
SERVICE_UNAVAILABLE503Temporarily unavailable. Retry with backoff.

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. Some routes use more specific codes (for example PRODUCTION_DOMAIN_NOT_ALLOWED); handle the ones you need and fall back to the HTTP status for the rest. Other 4xx statuses come back as REQUEST_FAILED.

Endpoints that return a plain array​

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

  • GET /v1/room/logs: Pass roomName and fieldKey: usageLogs, messages or recordUsageLogs.
  • GET /v1/sipcall/logs: Pass roomName or sipCallId, and fieldKey: transcripts or callSummary.

Try any request live in the API Sandbox.