Content, sources, and destinations

Content, sources, and destinations are the ingest and egress building blocks for Live API workflows. They are managed through the Media API and referenced by name in Live API resource inputs and outputs.

• Content is a named logical identifier for a stream. It carries no transport settings.
• Sources attach an ingest transport to content on a specific network. A source is how a stream physically arrives.
• Destinations define where a resource output is delivered. A destination is how a stream physically leaves.

Content

Create a content resource

curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/content/channel-1" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "displayName": "Channel 1"
    }
  }'

The content name is set in the URL path. It must match ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$. A content resource has no spec fields; it is a named identifier only.

Get and list content

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/content/channel-1" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/content" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

The response includes status.state, which is Active when one or more live resources are using this content, or Inactive otherwise.

Update content

PATCH updates metadata.displayName and metadata.labels only. Content has no mutable spec fields.

Delete content

curl -X DELETE "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/content/channel-1" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

If the resource does not exist, the API returns 204.

Sources

A source associates content with a transport on a specific network. When a Live API resource specifies a contentName as its input, the system resolves which sources supply that content on a network the resource can reach. You can also reference a source directly by sourceName to bypass content resolution.

Create a source

curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/sources/encoder-london" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "displayName": "Encoder London"
    },
    "spec": {
      "contentName": "channel-1",
      "networkName": "internet",
      "transport": {
        "type": "SRTListener",
        "port": 5000,
        "latency": 0.5,
        "maxBitrate": 30000000,
        "ipResource": {
          "type": "External"
        }
      }
    }
  }'

After creation, status.transport.urls contains the allocated connection URL for listener-type transports.

Update a source

networkName, transport type, and transport settings such as the listener port and latency are set at creation. Source PATCH supports the following changes:

For example, update the SRT listener allowlist without recreating the source:

curl -X PATCH "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/sources/encoder-london" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "spec": { "transport": { "allowList": ["<ENCODER_PUBLIC_IP>"] } } }'

Replace <ENCODER_PUBLIC_IP> with the encoder's public IP address. Retrieve the source afterwards and confirm spec.transport.allowList. Changes to the destination resource use a different update contract, described under Destinations.

Source transport types

The transport.type field determines which other fields apply.

SRTListener

The system opens an SRT listener. Encoders or upstream systems connect to it.

SRTCaller

The system calls out to a remote SRT listener.

UDP

The system receives a UDP stream.

SDI

Content arrives via SDI.

HLSPullInput

The system pulls from an HLS source.

List and get sources

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/sources" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/sources/encoder-london" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Source status includes state (Active or Inactive), networkDisplayName, shortId, and transport.urls for listener-type transports.

Source state and encoder connections

A source is Active while an active flow uses it. This state does not mean that an encoder is connected or that media is arriving. It can remain Active after FFmpeg or another encoder stops sending.

For an SRT listener input, request Running on the live resource first. Start the encoder as soon as the resource enters Starting. Do not wait for source Active before sending.

An established listener connection confirms that the encoder reached the listener. It does not confirm live media flow. After the live resource reaches Running, verify the expected video and audio through playback. See Verify media delivery.

Delete a source

curl -X DELETE "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/sources/encoder-london" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

If the source does not exist, the API returns 204.

Resolving content

When a live resource's input uses contentName instead of a direct sourceName, the platform selects a candidate that can supply that content. Network reachability constrains resolution: a source declares its networkName, and the flow must be able to reach that network.

If more than one source is attached to the same content name on reachable networks, the platform selects one. This resolution does not by itself guarantee seamless media-aware failover when an encoder stops sending. To select a specific source, reference it directly by sourceName. You can also use a flow input refiner to narrow the candidates.

Chain live resources

Content can also resolve to another flow's output rather than a source, if that flow publishes the content name on its output. This is what makes chaining flows together with contentName possible, as an alternative to referencing the upstream flow directly by flowName.

Inspect resolved inputs

Use ?$detailedStatus=true when reading a live resource's resolved inputs. Each status.inputs entry reports sourceName and sourceDisplayName for a source, or upstreamFlowName for another flow's output. Resolution still does not confirm media flow. See Monitor live resources for the full status object and source telemetry.

Destinations

A destination defines where a live resource output is delivered. A destination uses a transport for protocol-based egress, or an aquilaSourceId for Aquila-based routing. Only live resources that can reach the destination's network can use it.

Create a destination

curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/destinations/playout-system" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "displayName": "Playout System"
    },
    "spec": {
      "networkName": "internet",
      "transport": {
        "type": "SRTListener",
        "port": 6000,
        "latency": 0.5,
        "maxBitrate": 15000000,
        "ipResource": {
          "type": "External"
        }
      }
    }
  }'

Destination transport settings are create-time fields. Destination PATCH accepts metadata only. To change a passphrase, allowlist, network, or other transport setting, recreate the destination. Source and destination PATCH operations do not have the same mutability.

To send output to an Aquila source instead of a transport, set aquilaSourceId in place of transport:

"spec": {
  "aquilaSourceId": "1bfa932d36604506824fdd78642ad08f"
}

Destination transport types

Destinations support the following transport types:

For SRTListener destinations, status.transport.urls contains the allocated connection URL after creation.

List and get destinations

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/destinations" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/destinations/playout-system" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Destination status includes state (Active or Inactive), networkDisplayName, and transport.urls.

Delete a destination

curl -X DELETE "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/destinations/playout-system" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

What comes next

• Manage live channels and events: create live resources that read from your sources.
• Multiview: compose multiple source inputs into a single multiview output.
• Manage templates: create the encoding templates your live resources require.