Command-first documentation

Search the module, then move faster through the API

Find the exact module, copy the working request shape, and move from product workflow to API call without getting buried in the tree.

AI workflow helperDescribe what you want to buildOptional tool

Write the workflow in plain language. We will turn it into a GPT-ready brief you can use to generate requests, module order, and starter payloads.

Streams

On this page

Find an endpoint

10 endpoints

Search current page endpoints by name, HTTP verb, or URL

Search by endpoint name, HTTP verb, or URL, then jump straight to its request.

Streams Restreams Recordings

Streams gives each live feed a stable operational identity above the transport endpoint. Use it when an SRT or RTMP server exists, but your team also needs a durable stream name, role, stream ID, optional host binding, and saved inspection data.

This is the record operators use to follow one feed across monitoring, playback, troubleshooting, and automation. If a listener is restarted or a server object is reused, the stream identity stays the same.

role_name defines whether the feed is a publisher or receiver.
stream_id gives the feed a durable identifier for routing and operations.
host optionally ties the stream to a known remote source.
audio_settings and stream_meta_data store inspection results for later reuse.

Common stream records

Publisher on an SRT listener. Use this when a known encoder publishes into an SRT ingest point and you want a consistent stream record for dashboards and troubleshooting.

{
  "name": "Main stage publisher",
  "role_name": "publisher",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "module_name": "MODULE_SRT_SERVERS",
  "active": true
}

Receiver with host binding. Use this when a return feed should be associated with a specific remote host, such as a contribution partner or field unit.

{
  "name": "Remote return receiver",
  "role_name": "receiver",
  "stream_id": "receiver/main-stage/return-feed",
  "host": "198.51.100.24",
  "entity_id": "680400000000000000000001",
  "module_name": "MODULE_SRT_SERVERS",
  "active": true
}

Publisher on an RTMP server. Use this for RTMP contribution or origin workflows where the published feed needs a stable operational identity.

{
  "name": "RTMP primary publish",
  "role_name": "publisher",
  "stream_id": "studio/live/program",
  "entity_id": "680500000000000000000001",
  "module_name": "MODULE_RTMP_SERVERS",
  "active": true
}

If operators trigger actions from vMix, the create, start, and stop methods also include vMix Script examples.

Operational workflows

Register a feed once and keep it traceable

Create a stream record as soon as a contribution path is assigned. Use that record in dashboards, incident notes, and operator tools instead of referring only to the underlying server object.

Inspect a live source and save what matters

After a source connects, run getStreamInfo to inspect the real feed. Save the resulting audio layout or other media details in audio_settings or stream_meta_data with create, update, or setStreamInfo. This avoids rediscovering channel order, codec details, or other source-specific settings each time the feed returns.

Resolve the live address for playback or downstream routing

Use start to activate the stream, then getStreamInfo when a player, monitoring probe, or downstream workflow needs the concrete SRT or RTMP URL for the current session.

POST

/api/streams/create

Creates a new stream row in Callaba Engine.

The stream object does not replace an SRT server or RTMP server. It sits on top of one of those entities and keeps the stream-facing identity stable: name, role, stream id, optional host, and any saved audio metadata the team should not have to rediscover later.

If your team triggers provisioning from an operator workflow, the example set below also includes vMix Script tabs for the same create call.

Examples by preset

Start with the preset that matches the transport backing the stream. Publisher and receiver rows on top of SRT listeners behave differently in practice, and RTMP-backed rows normally carry a different stream id convention again.

Workflow-oriented use cases

Register a publisher stream above an SRT server

Use this when one managed SRT listener serves multiple named publisher flows and you want those flows to stay visible as first-class rows that operators can recognize quickly.

Persist receiver-side stream identity

Use this when routed or pulled traffic should keep a stable receiver-facing identity instead of only being implied by transport state.

Store stream-specific audio metadata

Use this when channel naming, layout, or per-track meaning should live with the stream object instead of being rediscovered every time.

SRT publisher stream

Use this when one SRT listener hosts a named publisher stream that operators should treat as a first-class object.

SRT publisher stream

SRT receiver stream

Use this when a receiver-side or returned feed should keep its own stream identity and optional host binding.

SRT receiver stream

RTMP publisher stream

Use this when the backing transport entity is an RTMP server rather than an SRT listener.

RTMP publisher stream

Stream with saved audio layout

Use this when channel layout and naming should be stored with the stream row after inspection.

Stream with saved audio layout

curl --request POST \
  --url http://localhost/api/streams/create \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Commentary audio stream",
  "role_name": "publisher",
  "stream_id": "publisher/commentary/audio-main",
  "entity_id": "680400000000000000000001",
  "module_name": "MODULE_SRT_SERVERS",
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Commentary",
        "channel_layout": "mono",
        "channels": [
          {
            "id": "FC",
            "name": "Commentary"
          }
        ]
      }
    ]
  },
  "active": true
}'

Request body parameters

Identity

name

string

Dashboard label: Name.

Human-facing name of the saved stream row.

role_name

string

Dashboard label: Role.

Typical product values include publisher, receiver, pusher, and puller.

stream_id

string

Stable stream identifier stored above the backing transport entity.

host

string

Optional host binding used when the stream identity should stay tied to a concrete remote peer.

Transport link

entity_id

string

Identifier of the backing transport-side entity, for example an SRT server or RTMP server.

module_name

string

Module family behind the stream row. In practice this is most often MODULE_SRT_SERVERS or MODULE_RTMP_SERVERS.

Metadata

audio_settings

object

Optional saved audio layout with named tracks and channels.

Runtime

active

boolean

Dashboard label: Enable once created.

Controls whether the stream row should be active right after provisioning.

Create stream

Response

Identity

_id / id / name / role_name / stream_id / host

mixed

Identifiers and the saved stream identity fields.

Transport link

entity_id / entityModel / module_name

mixed

Reference back to the transport object that owns or serves the stream.

Metadata

stream_meta_data / audio_settings

mixed

Saved inspection output, codec notes, and optional channel mapping metadata.

Runtime

active / created / modified

mixed

Runtime flag and backend-managed timestamps.

Operation result

success

boolean

Successful stream model responses expose success: true as a virtual field.

Response: Create stream

JSON

{
  "_id": "680600000000000000000001",
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "host": "",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "entityModel": "ServerModel",
  "module_name": "MODULE_SRT_SERVERS",
  "stream_meta_data": {
    "codec_name": "h264",
    "fps": "30/1"
  },
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Track-0",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "created": "2026-03-24T08:45:00.000Z",
  "modified": "2026-03-24T08:45:00.000Z",
  "active": true,
  "success": true
}

POST

/api/streams/getCount

POST

/api/streams/getAll

Returns the stream rows visible to the authenticated account.

Use this when the team needs one view of the active stream identities across SRT and RTMP-backed workflows, especially when publisher and receiver roles should stay easy to scan during operations.

Request body parameters

limit

integer

Optional page size for the listing query.

skip

integer

Optional offset for paginated listing.

sort

object

Optional sort descriptor. The dashboard store defaults to { created: 1 }.

filter

object

Optional filter object used for search and role/module filtering.

Get all streams

Response

array of stream objects

array

The backend returns a bare array of stream rows, not a wrapped object.

Response: Get all streams

JSON

[
  {
    "_id": "680600000000000000000001",
    "id": "680600000000000000000001",
    "name": "Main stage publisher",
    "role_name": "publisher",
    "host": "",
    "stream_id": "publisher/main-stage/srt-main",
    "entity_id": "680400000000000000000001",
    "entityModel": "ServerModel",
    "module_name": "MODULE_SRT_SERVERS",
    "stream_meta_data": {
      "codec_name": "h264",
      "fps": "30/1"
    },
    "audio_settings": {
      "streams": [
        {
          "id": 0,
          "name": "Track-0",
          "channel_layout": "stereo",
          "channels": [
            {
              "id": "FL",
              "name": "Left"
            },
            {
              "id": "FR",
              "name": "Right"
            }
          ]
        }
      ]
    },
    "created": "2026-03-24T08:45:00.000Z",
    "modified": "2026-03-24T08:45:00.000Z",
    "active": true,
    "success": true
  }
]

POST

/api/streams/getById

Loads one saved stream row by id.

Use this before editing when you need the current stream identity, associated transport entity, or stored audio settings exactly as they are persisted.

Request body parameters

string

Identifier of the stream row you want to load.

Get stream by id

Response

stream object

object

The backend returns the saved stream row with its transport link and any stored metadata.

Response: Get stream by id

JSON

{
  "_id": "680600000000000000000001",
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "host": "",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "entityModel": "ServerModel",
  "module_name": "MODULE_SRT_SERVERS",
  "stream_meta_data": {
    "codec_name": "h264",
    "fps": "30/1"
  },
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Track-0",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "created": "2026-03-24T08:45:00.000Z",
  "modified": "2026-03-24T08:45:00.000Z",
  "active": true,
  "success": true
}

POST

/api/streams/update

Updates a saved stream row.

In practice this is where teams rename a stream, adjust its role-facing metadata, attach or revise saved audio settings, or correct the stream id and host pairing after live inspection.

Request body parameters

string

Identifier of the stream row to update.

name / role_name / stream_id / host

mixed

Updated stream identity fields.

audio_settings

object

Optional replacement audio layout or saved channel naming data.

active

boolean

Current runtime-enabled flag after the update.

Update stream

curl --request POST \
  --url http://localhost/api/streams/update \
  --header 'x-access-token: <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "module_name": "MODULE_SRT_SERVERS",
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Program",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "active": true
}'

Response

updated stream object

object

The backend returns the updated stream row.

Response: Update stream

JSON

{
  "_id": "680600000000000000000001",
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "host": "",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "entityModel": "ServerModel",
  "module_name": "MODULE_SRT_SERVERS",
  "stream_meta_data": {
    "codec_name": "h264",
    "fps": "30/1"
  },
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Track-0",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "created": "2026-03-24T08:45:00.000Z",
  "modified": "2026-03-24T08:45:00.000Z",
  "active": true,
  "success": true
}

POST

/api/streams/setStreamInfo

DELETE

/api/streams/remove

POST

/api/streams/start

Starts the underlying stream runtime for the selected stream row.

This is the operational companion to stream provisioning. It matters when a saved stream identity should immediately become an active runtime flow that another team, player, or downstream step can rely on.

If this action is triggered from an operator workflow, the example set below includes a vMix Script tab as well.

Request body parameters

string

Identifier of the stream row to start.

Start stream

Response

started stream object

object

The backend returns the stream row after the start action is accepted.

Response: Start stream

JSON

{
  "_id": "680600000000000000000001",
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "host": "",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "entityModel": "ServerModel",
  "module_name": "MODULE_SRT_SERVERS",
  "stream_meta_data": {
    "codec_name": "h264",
    "fps": "30/1"
  },
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Track-0",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "created": "2026-03-24T08:45:00.000Z",
  "modified": "2026-03-24T08:45:00.000Z",
  "active": true,
  "success": true
}

POST

/api/streams/stop

Stops the runtime for the selected stream row.

Use this to take the stream offline without deleting the saved metadata and identity around it.

If this action is triggered from an operator workflow, the example set below includes a vMix Script tab as well.

Request body parameters

string

Identifier of the stream row to stop.

Stop stream

Response

stopped stream object

object

The backend returns the stream row after the stop action is accepted.

Response: Stop stream

JSON

{
  "_id": "680600000000000000000001",
  "id": "680600000000000000000001",
  "name": "Main stage publisher",
  "role_name": "publisher",
  "host": "",
  "stream_id": "publisher/main-stage/srt-main",
  "entity_id": "680400000000000000000001",
  "entityModel": "ServerModel",
  "module_name": "MODULE_SRT_SERVERS",
  "stream_meta_data": {
    "codec_name": "h264",
    "fps": "30/1"
  },
  "audio_settings": {
    "streams": [
      {
        "id": 0,
        "name": "Track-0",
        "channel_layout": "stereo",
        "channels": [
          {
            "id": "FL",
            "name": "Left"
          },
          {
            "id": "FR",
            "name": "Right"
          }
        ]
      }
    ]
  },
  "created": "2026-03-24T08:45:00.000Z",
  "modified": "2026-03-24T08:45:00.000Z",
  "active": true,
  "success": true
}

POST

/api/streams/getStreamInfo

Runs a stream inspection against a live URL and returns codec, audio, and timing details for the real upstream feed.

Use it when the team needs facts from the live signal before deciding what should be saved into the stream row or passed on to another workflow.

Request body parameters

stream_url

string

Live input URL that should be inspected with FFprobe.

Get stream info

Response

streams[]

array

FFprobe-style stream descriptors for video, audio, or data tracks discovered on the live input.

streams[].codec_name / codec_type

mixed

Codec identity for each discovered track.

streams[].width / height / avg_frame_rate

mixed

Representative video properties when the input includes a video track.

streams[].sample_rate / channels / channel_layout

mixed

Representative audio properties when the input includes audio tracks.

format

object

Top-level FFprobe format object for the inspected URL.

Response: Get stream info

JSON

{
  "streams": [
    {
      "index": 0,
      "codec_name": "h264",
      "codec_type": "video",
      "width": 1920,
      "height": 1080,
      "avg_frame_rate": "30/1",
      "pix_fmt": "yuv420p"
    },
    {
      "index": 1,
      "codec_name": "aac",
      "codec_type": "audio",
      "sample_rate": "48000",
      "channels": 2,
      "channel_layout": "stereo"
    }
  ],
  "format": {
    "filename": "srt://127.0.0.1:1936",
    "nb_streams": 2,
    "format_name": "mpegts",
    "start_time": "0.000000",
    "probe_score": 100
  }
}

Back toRestreams Next toRecordings