Skip to content

Restreaming API

Send a live stream on to up to five other services that take RTMP or RTMPS, at the same time. Each destination is billed per destination-hour while it is live.

This page is generated from the OpenAPI specification; the same text is inMarkdown for tools and AI assistants.

List a stream's destinations

GET/v1/streams/{playback_id}/destinations

The services a stream is sent on to, and how each is doing. Stream keys are never returned, only their last characters.

Path parameters

NameTypeDescription
playback_idrequiredstring

The stream’s playback_id.

Response 200

The destinations.

Fields
NameTypeDescription
destinationsrequiredarray of object
destinations[].idrequiredstring (uuid)
destinations[].namerequiredstring
destinations[].urlrequiredstring
destinations[].stream_key_hintrequiredstring

The last characters of the stream key.

destinations[].enabledrequiredboolean
destinations[].statusrequiredstring

One of "idle", "connecting", "live", "failing".

destinations[].last_errorrequiredstring or null
destinations[].status_updated_atrequiredstring (date-time) or null
destinations[].created_atrequiredstring (date-time)
destinations[].updated_atrequiredstring (date-time)
max_destinationsrequiredinteger

How many destinations a stream may have.

Errors

StatusCodeMeaning
404not_found

No such stream in your organization.

Terminal window
curl "https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/destinations" \
-H "Authorization: Bearer $CARDINAL_API_KEY"
Response 200
{
"destinations": [
{
"id": "3b4f9c2e-8d1a-4f6b-a2c7-9e5d1b0f4a83",
"name": "Our channel",
"url": "rtmps://live.example.com:443/app",
"stream_key_hint": "...mnop",
"enabled": true,
"status": "idle",
"last_error": null,
"status_updated_at": null,
"created_at": "2026-10-18T14:40:00Z",
"updated_at": "2026-10-18T14:40:00Z"
}
],
"max_destinations": 5
}

Add a destination

POST/v1/streams/{playback_id}/destinations

Sends the stream on to another service while it is live. Give the server URL and stream key the service shows you. The key is stored encrypted, never returned, and deleted an hour after the broadcast ends. Destinations on private networks, or Cardinal’s own ingest, are refused.

Path parameters

NameTypeDescription
playback_idrequiredstring

The stream’s playback_id.

Request body

NameTypeDescription
namerequiredstring

Shown to everyone who can see the stream.

urlrequiredstring

The service’s server URL: rtmps:// (plain rtmp:// is refused), without the key.

stream_keyrequiredstring
enabledboolean

Default true.

Response 201

The destination.

Fields
NameTypeDescription
idrequiredstring (uuid)
namerequiredstring
urlrequiredstring
stream_key_hintrequiredstring

The last characters of the stream key.

enabledrequiredboolean
statusrequiredstring

One of "idle", "connecting", "live", "failing".

last_errorrequiredstring or null
status_updated_atrequiredstring (date-time) or null
created_atrequiredstring (date-time)
updated_atrequiredstring (date-time)

Errors

StatusCodeMeaning
400invalid_body

The body is not a JSON object.

400missing_field

name, url or stream_key is missing.

400invalid_name

The name is not 1-80 visible characters, or contains the stream key.

400invalid_url

The URL is not an rtmps:// server address with an application path (plain rtmp:// is refused: it would send the key unencrypted), carries credentials, a query string, spaces or control characters (typed or percent-encoded), or contains the stream key.

400invalid_stream_key

The stream key is empty, too long, or has characters a stream key cannot.

400destination_unresolvable

The server name could not be found.

400destination_not_allowed

That server address cannot be used.

404not_found

No such stream in your organization.

409stream_ended

The stream has ended.

409destination_limit

The stream already has the most destinations allowed.

503restream_unconfigured

Restreaming is not available on this deployment.

503restream_unpriced

Restreaming is not available for this broadcast.

Terminal window
curl -X POST "https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/destinations" \
-H "Authorization: Bearer $CARDINAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Our channel",
"url": "rtmps://live.example.com:443/app",
"stream_key": "abcd-efgh-ijkl-mnop",
"enabled": true
}'
Response 201
{
"id": "3b4f9c2e-8d1a-4f6b-a2c7-9e5d1b0f4a83",
"name": "Our channel",
"url": "rtmps://live.example.com:443/app",
"stream_key_hint": "...mnop",
"enabled": true,
"status": "idle",
"last_error": null,
"status_updated_at": null,
"created_at": "2026-10-18T14:40:00Z",
"updated_at": "2026-10-18T14:40:00Z"
}

Pause, resume or rename a destination

PATCH/v1/streams/{playback_id}/destinations/{destination_id}

Path parameters

NameTypeDescription
playback_idrequiredstring

The stream’s playback_id.

destination_idrequiredstring (uuid)

The destination’s id.

Request body

NameTypeDescription
enabledboolean
namestring

Response 200

The destination as it now is.

Fields
NameTypeDescription
idrequiredstring (uuid)
namerequiredstring
urlrequiredstring
stream_key_hintrequiredstring

The last characters of the stream key.

enabledrequiredboolean
statusrequiredstring

One of "idle", "connecting", "live", "failing".

last_errorrequiredstring or null
status_updated_atrequiredstring (date-time) or null
created_atrequiredstring (date-time)
updated_atrequiredstring (date-time)

Errors

StatusCodeMeaning
400invalid_body

The body is not a JSON object.

400missing_field

Neither enabled nor name was given.

400invalid_name

The name is not 1-80 visible characters, or contains the stream key.

404not_found

No such stream or destination in your organization.

Terminal window
curl -X PATCH "https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/destinations/3b4f9c2e-8d1a-4f6b-a2c7-9e5d1b0f4a83" \
-H "Authorization: Bearer $CARDINAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": false
}'

Remove a destination

DELETE/v1/streams/{playback_id}/destinations/{destination_id}

Path parameters

NameTypeDescription
playback_idrequiredstring

The stream’s playback_id.

destination_idrequiredstring (uuid)

The destination’s id.

Response 204

Removed.

Errors

StatusCodeMeaning
404not_found

No such stream or destination in your organization.

Terminal window
curl -X DELETE "https://api.cardinalstreaming.com/v1/streams/1846bdac2d8c0ce0e846d4a3817012c9/destinations/3b4f9c2e-8d1a-4f6b-a2c7-9e5d1b0f4a83" \
-H "Authorization: Bearer $CARDINAL_API_KEY"