# Pearl REST API use Single Touch control

Single Touch control starts and stops a preconfigured group of recorders and publishers together with one action. The API can read its current state and toggle it.

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

| Method and path | What it does |
| --- | --- |
| `GET /system/singletouchcontrol` | Lists Single Touch control objects and their IDs |
| `GET /system/singletouchcontrol/{stcid}/state` | Reads the state of one object |
| `POST /system/singletouchcontrol/{stcid}/control/toggle` | Changes the state of one object |

**State fields.**

| Field | Meaning |
| --- | --- |
| `pressed` | Whether the Single Touch object is currently activated |
| `status` | Whether all its recorders and publishers started successfully |
| `recorders` | Aggregate counts for recorders |
| `publishers` | Aggregate counts for publishers |

Each aggregate block reports `total` (how many items the object covers), `active` (how many are currently running), and `success` (how many are without errors).

```json
{
  "status": "ok",
  "result": {
    "pressed": false,
    "status": true,
    "recorders": { "total": 5, "active": 0, "success": 5 },
    "publishers": { "total": 4, "active": 1, "success": 4 }
  }
}
```

**Which publishers participate.** A publisher is included in Single Touch control by its `common.single_touch` setting, which defaults to `true`. Set it to `false` on a publisher that should not start and stop with the group.

Note that `pressed` and `status` answer different questions: `pressed` says whether the group was activated, while `status` says whether everything in the group actually came up. A group can be `pressed: true` with `status: false` when some members failed to start.

An unknown Single Touch control ID returns 404 with a message such as `single touch control object '30' not found`.

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