Connection API

Use the Connection API to manage a Realtime SFU application's media resources. Your backend sends authenticated HTTPS requests, while endpoints exchange media and DataChannels with the SFU over WebRTC.

Base URL:

https://rtc.live.cloudflare.com/v1

Send Authorization: Bearer <APP_SECRET> and Content-Type: application/json. Keep the App Secret on trusted backend infrastructure. Endpoint authentication and resource authorization belong to your application.

Download the full OpenAPI schema for request and response fields.

To implement a connection, follow the browser and backend recipes for publication, reception, messages, or media with controls. Use this reference to look up operations and fields.

Create an application

Create an SFU app in the dashboard or through the Cloudflare account API. App creation uses your Cloudflare account authorization. The Connection API uses the resulting SFU App ID and App Secret.

The quickstart shows this setup with a Worker backend.

Session and track operations

The paths in this table are relative to the base URL:

Refer to sessions and tracks for publication and identifier ownership.

Correlate session creation

The optional correlationId query parameter on sessions/new is a diagnostic label. Repeating it creates another session. The API cannot look up sessions by this label. Retain the returned sessionId, and follow recovery guidance if the response is lost.

Inspect a session

Call GET /apps/{appId}/sessions/{sessionId} to inspect the session's media tracks and DataChannels. The response identifies media by mid and channels by their allocated id. For a remote resource, sessionId identifies its publisher:

{
  "tracks": [
    {
      "location": "local",
      "mid": "0",
      "trackName": "camera",
      "status": "inactive"
    }
  ],
  "dataChannels": [
    {
      "location": "remote",
      "sessionId": "<PUBLISHER_SESSION_ID>",
      "dataChannelName": "controls",
      "id": 2,
      "status": "active"
    }
  ]
}

Interpret the resource's status as follows:

A media track marked active does not prove that packets are arriving or playing. Use endpoint statistics to check delivery. Forced closure can leave a track listed as inactive.

The response contains resource state, not SDP or request history. Pending requests can still change it, even when the resource lists are empty. Follow retry and reconnect guidance before resuming mutations.

DataChannel operations

These operations act on the same session and negotiation state as its media tracks:

Refer to DataChannels for negotiated IDs, reliability, readiness, and reply access.

WebSocket adapter operations

Create adapters to ingest external audio or stream existing audio/video publications to WebSocket endpoints:

The WebSocket adapter reference covers formats, request limits, partial success, reconnect, and close behavior.

Batch resource operations

Track and DataChannel create, update, and close operations accept multiple entries in their tracks or dataChannels array. For example, publish camera and microphone tracks together, or request several publications in one receiving-session call. Each batch targets the session in the request URL.

For tracks/new and datachannels/new, keep every entry local or every entry remote. A remote batch can reference different publishing sessions. Follow the operation's limits when choosing its size. WebSocket adapter creation and closure accept one to four entries per request.

Handle responses and negotiation

Check the HTTP status, top-level errors, and every per-track or per-channel result. Public errors use errorCode and errorDescription. Preserve successful allocations from partially successful requests. Look up the code and its next action in Error codes.

Complete any required SDP exchange before starting the next mutation on that session. Other sessions can proceed independently. Connection patterns gives the request sequences, including how to answer an SFU offer. Negotiation and session lifecycle explains concurrent handlers, uncertain request outcomes, and retries.

Network connectivity

Configure endpoint ICE, STUN, and TURN as part of connection preparation. That section also covers connection waits and candidate gathering.

Learn with an example

Run the video room to follow backend session and track operations. The DataChannel example shows the same API boundary in a small local Node.js server.