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

# Devices

> API endpoints for listing and managing enrolled devices

## List Devices

Returns all devices enrolled in the authenticated organization.

```
GET /api/devices
```

### Response

```json theme={null}
[
  {
    "id": "dev_01hx...",
    "name": "alice-macbook-pro",
    "machine_id": "...",
    "status": "active",
    "enrolled_at": "2025-09-01T12:00:00Z",
    "last_seen_at": "2025-10-14T17:55:00Z",
    "metadata": {}
  }
]
```

| Field          | Type   | Description                               |
| -------------- | ------ | ----------------------------------------- |
| `id`           | string | Device ID                                 |
| `name`         | string | Hostname reported at enrollment           |
| `machine_id`   | string | Unique hardware identifier                |
| `status`       | string | `active` or `disabled`                    |
| `enrolled_at`  | string | ISO 8601 enrollment timestamp             |
| `last_seen_at` | string | ISO 8601 last telemetry timestamp         |
| `metadata`     | object | Arbitrary agent-reported metadata (JSONB) |

***

## Disable a Device

Suspends a device. It remains enrolled but is excluded from analytics.

```
POST /api/devices/:device_id/disable
```

### Response

`204 No Content`

***

## Enable a Device

Re-activates a previously disabled device.

```
POST /api/devices/:device_id/enable
```

### Response

`204 No Content`

***

## Delete a Device

Permanently removes a device and all associated telemetry.

```
DELETE /api/devices/:device_id
```

<Warning>
  This action is irreversible. All telemetry history for the device is deleted.
</Warning>

### Response

`204 No Content`

### Errors

| Code  | Description                                    |
| ----- | ---------------------------------------------- |
| `403` | Caller does not have `ORG_ADMIN` role          |
| `404` | Device not found or belongs to a different org |