# Pearl REST API list channels, encoders, and switch layouts

Channels are the core objects on a Pearl device: each one has encoders, publishers, and layouts. The channel ID (`cid`) is the logical channel number shown in the Pearl Admin panel.

*Applies to: Pearl-2, Pearl Mini, Pearl Nexus, Pearl Nano.*

```
GET /api/v2.0/channels
```

By default this returns the ID and name of every channel. Query parameters expand the response:

| Parameter | Effect |
| --- | --- |
| `ids` | Comma-separated channel IDs to filter by, for example `ids=1,2` |
| `publishers` | Include each publisher's ID, type, and name. Must be true for the two options below to take effect |
| `publishers-status` | Include publisher status |
| `publishers-settings` | Include publisher configuration |
| `encoders` | Include video and audio encoder configuration |
| `active_layout` | Include the currently active layout and its sources |

**Encoder fields** returned per channel include `id`, `type` (`video` or `audio`), `name` (such as `H.264` or `AAC`), `resolution`, `framerate` (1 to 99), `bitrate` (1 to 50000 kbit/s), and `channels` for audio (1 for mono, 2 for stereo).

**Renaming a channel.** Names are 1 to 128 characters and are passed as a query parameter:

```
GET /api/v2.0/channels/{cid}/name
PUT /api/v2.0/channels/{cid}/name?name=Main%20Stage
```

**Switching layouts.** The active layout is changed by ID:

```
PUT /api/v2.0/channels/{cid}/layouts/active?id=1
```

The layout ID is auto-assigned. Read the current one from the `active_layout` block of the channel list, which also reports the layout's `name` and its video and audio `sources`. A request naming a channel that does not exist returns 404.

**Device differences**

- **Pearl Nano:** Pearl Nano has a single layout and does not support switching layouts.

> product: pearl-family · topic: layout · source: pearl-rest-api.md · updated: Oct 7, 2026