Restreams API (multistream)
Create restreams to push one live stream to multiple destinations (YouTube, Twitch, Facebook, TikTok, Kick, or custom RTMP). YouTube, Twitch and Facebook have a standard ingest address; for TikTok, Kick and custom RTMP send the server URL and key from the platform, otherwise the destination is created switched off. You get a single ingest URL and key; we relay to all configured destinations. Recording controls: Recording.
Create a restream
curl -s -X POST https://api.dcast.pro/api/v1/restreams \
-H "Authorization: Bearer pk_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"title": "My Multistream",
"sourceStreamId": "optional-live-stream-id",
"destinations": [
{ "platform": "YOUTUBE", "streamKey": "your-youtube-key" },
{ "platform": "CUSTOM", "streamKey": "key", "rtmpUrl": "rtmp://<your-rtmp-host>/live" }
]
}'title is required. For a standalone multistream ingest, send {"title":"…","destinations":[…]} and do not send streamId or sourceStreamId. Those fields are only for linking to a live stream you already created via POST /streams; a wrong or foreign id returns 400. A destination rtmpUrl is validated when the restream is created: a host that does not resolve or is not allowed is refused 400 BAD_REQUEST with destinations[i].rtmpUrl in error.field, so replace the placeholder in the example with your real RTMP address.
Response includes restream id and source stream key. Use /encoder-urls to retrieve RTMP/SRT/WHIP ingest URLs.
Instead of pushing from an encoder, DCAST can produce the input itself. Set sourceType on create or PUT /restreams/{id}: http with sourceUrl (an http(s) HLS or media URL we pull), srt-pull with sourceUrl = srt://host:port (query options mode=caller|rendezvous, latency in microseconds, passphrase), or file with sourceVideoId (a ready video in your library, played in a loop). The input starts with POST /restreams/{id}/start and ends with /stop. A missing or disallowed address is refused 400 BAD_REQUEST with the field name in error.field. To check the source before going live, connect only the input with POST /restreams/{id}/input/start (no destination starts; the answer carries connected, kind, workerId and alreadyRunning) and disconnect it with POST /restreams/{id}/input/stop, which is refused 409 while the restream is on air.
Canonical pagination
curl -s -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
"https://api.dcast.pro/api/v1/restreams?page=1&limit=20"
# Response
{
"success": true,
"data": {
"restreams": [ /* ... */ ],
"pagination": { "page": 1, "limit": 20, "total": 7, "pages": 1 }
}
}Encoder URLs and start/stop
GET https://api.dcast.pro/api/v1/restreams/{id}/encoder-urls
POST https://api.dcast.pro/api/v1/restreams/{id}/start
POST https://api.dcast.pro/api/v1/restreams/{id}/stop
POST https://api.dcast.pro/api/v1/restreams/{id}/input/start
POST https://api.dcast.pro/api/v1/restreams/{id}/input/stop
Authorization: Bearer pk_YOUR_KEY_HEREResponse from /encoder-urls exposes rtmp, rtmps, srt (literal publishable streamid), and whip. The rtmps field is always present and is null until RTMPS input is enabled. All hostnames are r.dcast.pro (the canonical restream DNS pool) — never a worker hostname.
Copy srt exactly as returned. Once every enabled worker in the restream pool is ready, streamid is restream/sk_rstrm_…; until then the API returns #!::r=restream/…,m=publish. Previously issued addresses remain valid. Do not percent-encode the value for ffmpeg, OBS or vMix.
# Quick test (paste srt verbatim):
ffmpeg -re -f lavfi -i testsrc2=size=1280x720:rate=30 \
-f lavfi -i sine=frequency=440 \
-c:v libx264 -preset veryfast -b:v 1500k -g 60 \
-c:a aac -b:a 96k \
-f mpegts "srt://r.dcast.pro:10080?streamid=restream/sk_rstrm_<…>&mode=caller&latency=500000"The latency token of an SRT URL is read by ffmpeg and libsrt as microseconds, not milliseconds. Paste the srt field from /encoder-urls verbatim and the conversion is never yours to make; the band in force is published under srtConfig.latency in https://api.dcast.pro/api/v1/docs/openapi.json.
Live preview player
GET /restreams/:id/preview-url returns the canonical HTTP-FLV preview URL for the restream's incoming source. The hostname is always api.dcast.pro — partners never see a worker hostname. When the player hits that URL we 302-redirect to the current preview worker (worker rebalance is transparent; flv.js / mpegts.js follow redirects natively). The same URL is what the cabinet plays in its «Preview» pane and what the cabinet WebSocket event stream:preview_ready emits.
curl -s -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
https://api.dcast.pro/api/v1/restreams/{restreamId}/preview-url
# 200 — restream is publishing and the worker-side preview is up
{
"success": true,
"data": {
"httpFlvUrl": "https://api.dcast.pro/api/v1/restreams/{restreamId}/preview.flv?token=eyJ...",
"expiresAt": "2026-05-27T17:43:56.103Z",
"isLive": true
}
}
# 202 — restream has not received a publish yet. Caller may poll every 5–15s.
{
"success": true,
"data": {
"httpFlvUrl": null,
"expiresAt": null,
"isLive": false,
"reason": "restream_not_publishing"
}
}
# 202 — source publish received but the worker-side preview transcoder
# has not yet published the _preview mount back to SRS (transient,
# normally <2s after the first source publish). Retry after 1–2s.
{
"success": true,
"data": {
"httpFlvUrl": null,
"expiresAt": null,
"isLive": false,
"reason": "preview_warming_up"
}
}
# 404 — wrong owner or restream does not exist.
{ "success": false, "error": { "code": "NOT_FOUND", "message": "Restream not found" } }Token lifetime
The ?token=... in the URL is a short-lived signed JWT (~5 minutes, master-token TTL). Use the returned expiresAt to refresh before it expires; re-fetch on a ≤ 4-minute cadence for long-running preview sessions.
flv.js example (browser)
import mpegts from 'mpegts.js'; // or 'flv.js' — interchangeable
async function attachRestreamPreview(videoEl, restreamId, apiKey) {
const r = await fetch(
'https://api.dcast.pro/api/v1/restreams/' + restreamId + '/preview-url',
{ headers: { Authorization: 'Bearer ' + apiKey } }
);
const { data } = await r.json();
if (!data.isLive) {
setTimeout(() => attachRestreamPreview(videoEl, restreamId, apiKey), 10_000);
return;
}
const player = mpegts.createPlayer({ type: 'flv', url: data.httpFlvUrl, isLive: true });
player.attachMediaElement(videoEl);
player.load();
player.play();
const refreshInMs = Math.max(
60_000,
new Date(data.expiresAt).getTime() - Date.now() - 60_000
);
setTimeout(() => {
player.destroy();
attachRestreamPreview(videoEl, restreamId, apiKey);
}, refreshInMs);
}Works for FULL_ACCESS, STANDARD, and READ_ONLY pk_* keys.
Destinations — masked keys on read
On every read endpoint (GET /restreams, GET /restreams/:id), each destinations[*].streamKey is returned masked as "***". Destination keys are write-only: the POST /restreams response lists each destination with only id, platform, enabled and status (no streamKey), and the PUT /restreams/:id response lists destinations without a key. The key is the one you got from the destination platform; keep your own copy.
Patch a destination (partial update)
curl -s -X PATCH https://api.dcast.pro/api/v1/restreams/{id}/destinations/{destId} \
-H "Authorization: Bearer pk_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{"enabled":false}'
# Any subset of the four fields is accepted; at least one is required.
# - enabled (boolean)
# - displayName (string | null)
# - rtmpUrl (string, non-empty)
# - platform (string, normalised to uppercase: CUSTOM/YOUTUBE/TWITCH/FACEBOOK/INSTAGRAM/TIKTOK/KICK/TELEGRAM)
#
# streamKey is NOT patchable here. To change a destination's key, send the
# new key from the platform in PUT /restreams/:id (see below).PATCH is partial: send only the fields you want to change. Empty body returns 400 BAD_REQUEST ("include at least one of: enabled, displayName, rtmpUrl, platform"). Foreign destId returns 404 NOT_FOUND.
Change a destination's key
Send the destination with its id and the new key from YouTube / Twitch / Facebook / your RTMP server in PUT /restreams/:id. A field you do not send keeps its stored value; a streamKey that is absent, null or the masked "***" that reads return is not a key and leaves the stored one unchanged (send "" only to clear it). On an ACTIVE restream the running forwarder keeps the old key until you stop and start the restream.
curl -s -X PUT https://api.dcast.pro/api/v1/restreams/{id} \
-H "Authorization: Bearer pk_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{"destinations":[{"id":"{destId}","platform":"YOUTUBE","streamKey":"NEW_KEY_FROM_YOUTUBE","rtmpUrl":"rtmp://a.rtmp.youtube.com/live2"}]}'rotate-key (store a new platform key)
curl -s -X POST https://api.dcast.pro/api/v1/restreams/{id}/destinations/{destId}/rotate-key \
-H "Authorization: Bearer pk_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{"streamKey":"NEW_KEY_FROM_YOUTUBE"}'
# Response
{
"success": true,
"data": {
"id": "...",
"restreamId": "...",
"platform": "YOUTUBE",
"rtmpUrl": "rtmp://a.rtmp.youtube.com/live2",
"status": "INACTIVE",
"streamKey": "NEW_KEY_FROM_YOUTUBE",
"runtimeApplied": true,
"note": "New key takes effect on the next push from your encoder."
}
}Requires { "streamKey": "<new platform key>" }: the key is issued by YouTube / Twitch / Facebook, never by DCAST, and is stored as sent. A request without it (absent, empty, or the masked "***", which is not a key) is refused 400 BAD_REQUEST and the stored key stays. On an ACTIVE restream runtimeApplied is false: the running forwarder keeps the old key until stop + start. The response echoes the key you sent; subsequent reads mask it back to "***".
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /restreams | List restreams (canonical pagination) |
| POST | /restreams | Create restream (the response omits destination keys) |
| GET | /restreams/:id | Restream details (destination keys masked) |
| GET | /restreams/:id/encoder-urls | Ingest URLs (RTMP / SRT / WHIP) |
| GET | /restreams/:id/preview-url | Live HTTP-FLV preview URL for flv.js playback (the same URL the cabinet renders) |
| POST | /restreams/:id/start | Start restream |
| POST | /restreams/:id/stop | Stop restream |
| PUT | /restreams/:id | Update restream (a destination field you do not send keeps its stored value; response has no keys) |
| PATCH | /restreams/:id/destinations/:destId | Partial-update a destination — any subset of enabled, displayName, rtmpUrl, platform (at least one required) |
| POST | /restreams/:id/destinations/:destId/rotate-key | Replace the stored streamKey with the new platform key sent in the body (streamKey, required) |
| DELETE | /restreams/:id | Delete restream |
| POST | /restreams/:id/record/start | Start recording |
| POST | /restreams/:id/record/stop | Stop recording |
| GET | /restreams/:id/record/status | Recording status |
Platforms: YOUTUBE, TWITCH, FACEBOOK, CUSTOM (requires rtmpUrl).
Destination validation (before /start)
POST /restreams/:id/start runs a pre-flight gate over destinations[] before touching worker state. The pre-flight enforces the following per destination, after trimming whitespace:
enabledmust not befalse(default istrue; toggle viaPATCH /restreams/:id/destinations/:destId).- Either a connected
platformAccountId(OAuth-backed destination) or a non-emptystreamKeyand artmpUrlcontaining"://". - For
platform="CUSTOM"there is no default RTMP host — you must supplyrtmpUrlon create / update.YOUTUBE/TWITCH/FACEBOOKfall back to the standard ingest URL whenrtmpUrlis omitted. streamKeyis whitespace-trimmed before the length check, so" "and the masked placeholder"***"(echoed back from read responses) will not pass — never round-trip the masked value intoPUT /restreams/:id. A destination entry sent with itsidinPUTis written whole, so include the real key each time (an omitted key is stored empty), or leave that destination out ofdestinations[]to keep it unchanged.
If at least one destination passes the gate the restream starts; the others are still attempted by the worker but failures stay scoped to that destination's status. If every destination is switched off, /start returns 400 BAD_REQUEST (“No destination is switched on”); if a switched-on destination lacks its stream key or RTMP URL, it returns 422 PRECONDITION_FAILED (see below).
Error envelope codes
Lifecycle endpoints (/start, /stop) return error.code that mirrors the HTTP status semantics, so partner clients can branch on the code alone without parsing HTTP. Previously every lifecycle failure collapsed to BAD_REQUEST while HTTP varied — that has been corrected.
| HTTP | error.code | Meaning & example trigger |
|---|---|---|
| 400 | BAD_REQUEST | Malformed input the caller can fix (e.g. /start with sourceStreamId set but no source signal received yet). |
| 404 | NOT_FOUND | Restream not found, or not owned by the caller. |
| 409 | CONFLICT | Concurrent /start in flight (Redis NX lock loss), or restream is already ACTIVE. |
| 409 | PLAN_RESTREAM_LEG_LIMIT_REACHED | Starting would put more outgoing legs on air than the plan allows at once, counted over the whole account: 2 on Free, 4 on Star, 6 on Pro, 10 on VIP. PATCH /restreams/:id/destinations/:destId and PUT /restreams/:id answer the same when they switch a leg on while the restream is running. The error carries limit, current, wanted, total and plan (see Errors and limits). |
| 422 | PRECONDITION_FAILED | Pre-flight rejected: a switched-on destination is missing its stream key or RTMP URL. (When every destination is switched off the answer is 400 BAD_REQUEST.) |
| 502 | UPSTREAM_ERROR | OAuth-backed destination provisioning failed at the third-party platform. |
| 503 | SERVICE_UNAVAILABLE | No fleet worker available for the restream right now — safe to retry. |
| 5xx | INTERNAL_ERROR | Unhandled server error; retry with backoff and report if persistent. |
Security & scope
Restream endpoints are creator-scoped. Foreign restream ids return 404 NOT_FOUND. pk_* keys cannot list other creators' restreams, cannot bind destinations to streams they do not own, and cannot read another account's un-masked destination keys.

