# Pearl REST API publisher settings for RTMP, RTSP, and HLS

Publisher settings are read and written on a single path per publisher, and every settings object shares the same outer structure regardless of protocol.

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

| Method and path | What it does |
| --- | --- |
| `GET /channels/{cid}/publishers/{pid}/settings` | Reads current settings |
| `PUT /channels/{cid}/publishers/{pid}/settings` | Replaces settings completely |
| `PATCH /channels/{cid}/publishers/{pid}/settings` | Updates only the fields you send |

**Shared structure.** Every settings body carries a `type` field naming the protocol, a `common` block, and one protocol-specific block named after the type:

- `common.enabled` — whether the publisher is enabled. Default `false`.
- `common.single_touch` — whether Single Touch control includes this publisher. Default `true`.

Use `PATCH` for a targeted change, such as switching a destination URL without resending credentials.

**The field names below apply to requests.** A read of the same publisher returns a flat structure using different, hyphenated field names — `common.enabled` is returned as `started`, and `disable_audio` is returned as `disable-audio`. See "Pearl REST API publisher settings field names differ between reads and writes" for the full mapping.

**RTMP push** (`type: "rtmp"`, block `rtmp`):

| Field | Notes |
| --- | --- |
| `url` | Destination URL, up to 500 characters |
| `stream` | Stream key or name, up to 500 characters |
| `username` / `password` | Up to 250 characters each |
| `disable_audio` | Default `false` |

**RTSP announce** (`type: "rtsp"`, block `rtsp`):

| Field | Notes |
| --- | --- |
| `url` | Destination URL, up to 500 characters |
| `transport` | `tcp` or `udp`. Default `udp` |
| `username` / `password` | Up to 250 characters each |
| `disable_audio` | Default `false` |

**HLS push** (`type: "hls"`, block `hls`):

| Field | Notes |
| --- | --- |
| `url` | Ingest URL |
| `master_pl_url` | Master playlist URL |
| `username` / `password` | Up to 250 characters each |
| `segment_duration` | 1 to 8 seconds. Default `6` |
| `list_size` | Minimum 1. Default `6` |
| `user_agent` | Up to 100 characters |
| `http_method` | Default `POST` |
| `media_seg_tmpl` | Media segment template, up to 1000 characters |
| `disable_audio` | Default `false` |

A PATCH that changes only the RTMP destination:

```json
{
  "rtmp": { "url": "rtmp://192.168.86.57", "stream": "new-key" },
  "common": { "enabled": true }
}
```

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