> For the complete documentation index, see [llms.txt](https://docs.cstplus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cstplus.org/api-reference/general/channels.md).

# Channels

## List all channels

<mark style="color:blue;">`GET`</mark> `http://YOUR_SERVER:8080/api/channels`

Returns all channels on this server with their current status and configuration.

#### Headers

| Name                                            | Type   | Description           |
| ----------------------------------------------- | ------ | --------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer YOUR\_API\_KEY |

{% tabs %}
{% tab title="200: OK Array of channel objects" %}

```json
[
  {
    "id": "ch_abc123",
    "slug": "news",
    "name": "News 24",
    "status": "on-air",
    "renderProgress": 100,
    "totalDurationSec": 28800,
    "programMode": "loop",
    "config": {
      "contentDir": "/opt/cstplus/content/news",
      "resolution": { "width": 1280, "height": 720 },
      "fps": 25,
      "videoCodec": "h264",
      "audioCodec": "aac"
    },
    "createdAt": "2026-06-20T10:00:00Z",
    "updatedAt": "2026-06-25T08:00:00Z"
  }
]
```

{% endtab %}

{% tab title="401: Unauthorized " %}

```json
{ "error": "unauthorized" }
```

{% endtab %}
{% endtabs %}

***

### Get channel

## Get a single channel

<mark style="color:blue;">`GET`</mark> `http://YOUR_SERVER:8080/api/channels/{id}`

Returns a single channel by ID or slug.

#### Path Parameters

| Name                                 | Type   | Description        |
| ------------------------------------ | ------ | ------------------ |
| id<mark style="color:red;">\*</mark> | string | Channel ID or slug |

#### Headers

| Name                                            | Type   | Description           |
| ----------------------------------------------- | ------ | --------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer YOUR\_API\_KEY |

{% tabs %}
{% tab title="200: OK Channel object" %}

```json
{
  "id": "ch_abc123",
  "slug": "news",
  "name": "News 24",
  "status": "on-air",
  "renderProgress": 100,
  "totalDurationSec": 28800,
  "programMode": "loop",
  "lastError": null,
  "renderWarnings": []
}
```

{% endtab %}

{% tab title="404: Not Found " %}

```json
{ "error": "not_found", "message": "Channel 'sport-2' does not exist" }
```

{% endtab %}
{% endtabs %}

***

### Start channel

## Start a channel

<mark style="color:green;">`POST`</mark> `http://YOUR_SERVER:8080/api/channels/{id}/start`

Starts the channel's HLS playback loop. The channel must be in `rendered`, `stopped`, or `error` state.

#### Path Parameters

| Name                                 | Type   | Description        |
| ------------------------------------ | ------ | ------------------ |
| id<mark style="color:red;">\*</mark> | string | Channel ID or slug |

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer YOUR\_API\_KEY (requires `channels:write`) |

{% tabs %}
{% tab title="200: OK " %}

```json
{ "status": "on-air" }
```

{% endtab %}

{% tab title="400: Bad Request Channel is not in a startable state" %}

```json
{ "error": "validation_failed", "message": "Channel must be rendered before starting" }
```

{% endtab %}
{% endtabs %}

***

### Stop channel

## Stop a channel

<mark style="color:green;">`POST`</mark> `http://YOUR_SERVER:8080/api/channels/{id}/stop`

Stops the channel's HLS playback loop. Active viewer sessions will receive 404 on the next segment request.

#### Path Parameters

| Name                                 | Type   | Description        |
| ------------------------------------ | ------ | ------------------ |
| id<mark style="color:red;">\*</mark> | string | Channel ID or slug |

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer YOUR\_API\_KEY (requires `channels:write`) |

{% tabs %}
{% tab title="200: OK " %}

```json
{ "status": "stopped" }
```

{% endtab %}
{% endtabs %}

***

### Restart channel

## Restart a channel

<mark style="color:green;">`POST`</mark> `http://YOUR_SERVER:8080/api/channels/{id}/restart`

Stops and immediately restarts the channel. In schedule mode, the restart reseeks to the correct clock position.

#### Path Parameters

| Name                                 | Type   | Description        |
| ------------------------------------ | ------ | ------------------ |
| id<mark style="color:red;">\*</mark> | string | Channel ID or slug |

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer YOUR\_API\_KEY (requires `channels:write`) |

{% tabs %}
{% tab title="200: OK " %}

```json
{ "status": "on-air" }
```

{% endtab %}
{% endtabs %}

***

### Render channel

## Queue a render

<mark style="color:green;">`POST`</mark> `http://YOUR_SERVER:8080/api/channels/{id}/render`

Queues a new render for the channel. If the channel is on air, it keeps running the current reel until the new render completes, then switches over automatically.

#### Path Parameters

| Name                                 | Type   | Description        |
| ------------------------------------ | ------ | ------------------ |
| id<mark style="color:red;">\*</mark> | string | Channel ID or slug |

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer YOUR\_API\_KEY (requires `channels:write`) |

{% tabs %}
{% tab title="200: OK Render queued" %}

```json
{ "status": "queued" }
```

{% endtab %}
{% endtabs %}

***

### Channel status values

| Status      | Meaning                                    |
| ----------- | ------------------------------------------ |
| `created`   | Channel exists but has never been rendered |
| `queued`    | Render is waiting in the queue             |
| `rendering` | Render is in progress                      |
| `rendered`  | Render complete, ready to start            |
| `on-air`    | Channel is live and broadcasting           |
| `stopped`   | Channel was stopped manually               |
| `error`     | Channel crashed or render failed           |

{% hint style="info" %}
Poll `GET /api/channels/{id}` to track render progress. The `renderProgress` field goes from 0 to 100 during rendering.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cstplus.org/api-reference/general/channels.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.