> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquestr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Devices

> Register devices, list, patch, revoke, command history.

# Devices

Base: `/v1/devices`. Authenticate with an API key:

```http theme={"system"}
Authorization: Bearer sk_live_…
```

| Method   | Path            | Notes                                                                                                |
| -------- | --------------- | ---------------------------------------------------------------------------------------------------- |
| `POST`   | `/`             | Create device bound to license → `{ data }`                                                          |
| `GET`    | `/`             | List for org / key scope; optional `license_id`, `status`, `external_device_id`; `page` / `per_page` |
| `GET`    | `/:id`          | Retrieve → `{ data }`                                                                                |
| `PATCH`  | `/:id`          | Update `name`, `adapter`, and/or `external_device_id`                                                |
| `POST`   | `/:id/revoke`   | Revoke → `{ data }`                                                                                  |
| `DELETE` | `/:id`          | Must already be **revoked** → `{ data: { ok: true } }`                                               |
| `GET`    | `/:id/commands` | Command history → `{ data, meta }`                                                                   |

Device `status` lifecycle: `pending` → `enrolled` (Gateway) → `revoked`. Lists include all three unless you pass `?status=`.

Device activation / WebSocket is handled by the **Device Gateway**, not these routes.

Functions are nested under the same prefix — see [Functions API](/api/functions).

## External id

Optional `external_device_id` (string, max 200). Trimmed; empty → `null`. Unique per customer when set (`409` on conflict). Returned on device payloads. Filter list with `?external_device_id=` (still requires `customer_id`). Updatable via `PATCH`.

## Create device

```bash theme={"system"}
curl -s -X POST "$API/v1/devices" \
  -H "Authorization: Bearer $ORQUESTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "ORG_UUID",
    "license_id": "LICENSE_UUID",
    "adapter": "sicarv4",
    "name": "Caja 1",
    "external_device_id": "caja-1"
  }'
```

| Field                | Type           | Required | Notes                                                            |
| -------------------- | -------------- | -------- | ---------------------------------------------------------------- |
| `customer_id`        | UUID           | Yes      |                                                                  |
| `license_id`         | UUID           | Yes      | Must belong to org; active; within `max_devices`                 |
| `adapter`            | enum           | Yes      | `sicarv4` (Sicar V4) · `eleventa` · `microsip` · `mybusinesspos` |
| `name`               | string         | No       | 1–200 chars                                                      |
| `external_device_id` | string \| null | No       | Integration id; unique per customer                              |

Returns `201` with `{ "data": { …, "status": "pending", … } }` until the Gateway enrolls the device.

## List devices

By default returns **all** device statuses for the customer (`pending`, `enrolled`, `revoked`). Filter with `license_id` and/or `status`.

```bash theme={"system"}
# All devices for a customer (every status)
curl -s "$API/v1/devices?customer_id=ORG_UUID" \
  -H "Authorization: Bearer $ORQUESTR_API_KEY"
```

```bash theme={"system"}
# Devices on one license
curl -s "$API/v1/devices?customer_id=ORG_UUID&license_id=LICENSE_UUID" \
  -H "Authorization: Bearer $ORQUESTR_API_KEY"
```

```bash theme={"system"}
# Only enrolled devices
curl -s "$API/v1/devices?customer_id=ORG_UUID&status=enrolled" \
  -H "Authorization: Bearer $ORQUESTR_API_KEY"
```

```bash theme={"system"}
# Only revoked devices
curl -s "$API/v1/devices?customer_id=ORG_UUID&status=revoked" \
  -H "Authorization: Bearer $ORQUESTR_API_KEY"
```

| Query                | Required | Notes                                                    |
| -------------------- | -------- | -------------------------------------------------------- |
| `customer_id`        | Yes      | UUID                                                     |
| `license_id`         | No       | UUID — devices bound to that license                     |
| `status`             | No       | `pending` · `enrolled` · `revoked`                       |
| `external_device_id` | No       | Exact match filter                                       |
| `page`               | No       | Pagination                                               |
| `per_page`           | No       | Max 100; if both `page` and `per_page` omitted, full set |

Response: `{ data: Device[], meta: { page, per_page, total_pages, total_count } }`. Revoked devices sort last.

You can also list by license path: [`GET /v1/licenses/{id}/devices`](/api/licenses#list-devices-for-a-license) (same statuses / `status` filter).

API keys optionally filter by customer / license / device when those filters were set at key creation.

## Patch device

```bash theme={"system"}
curl -s -X PATCH "$API/v1/devices/$DEVICE_ID" \
  -H "Authorization: Bearer $ORQUESTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Caja principal","adapter":"sicarv4","external_device_id":"caja-1"}'
```

At least one of `name`, `adapter`, or `external_device_id` is required. Cannot patch revoked devices.

## Delete device

```bash theme={"system"}
curl -s -X DELETE "$API/v1/devices/$DEVICE_ID" \
  -H "Authorization: Bearer $ORQUESTR_API_KEY"
```

Only **revoked** devices can be deleted (`409` if `pending`/`enrolled`). Success: `{ "data": { "ok": true } }`.

## Command history

```bash theme={"system"}
curl -s "$API/v1/devices/$DEVICE_ID/commands?page=1&per_page=50&status=ok" \
  -H "Authorization: Bearer $ORQUESTR_API_KEY"
```

| Query      | Default          | Notes                                  |
| ---------- | ---------------- | -------------------------------------- |
| `page`     | —                | Positive integer                       |
| `per_page` | `20` when paging | Max **100**                            |
| `source`   | —                | `web` · `api` · `mcp`                  |
| `status`   | —                | `pending` · `ok` · `error` · `timeout` |
| `from`     | —                | ISO timestamp (inclusive)              |
| `to`       | —                | ISO timestamp (inclusive)              |

If both `page` and `per_page` are omitted, returns the full command set. Response: `{ data: Command[], meta: { page, per_page, total_pages, total_count } }`. Works for **revoked** devices (historical audit).