> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Devices — full verified contracts

Sources: `modules/Devices/Routes/api.php`, `Interfaces/Http/Controllers/DeviceController.php`, `Interfaces/Http/Requests/RegisterDeviceRequest.php`, `SetDevicePushRequest.php`, `Domain/Platform.php`, Core `ApiResponse.php`. All paths below are relative to `/api/v1` **only if this is the installed route version prefix**; verify runtime base URL.

**Common:** `Authorization: Bearer <token>`, `Accept: application/json`; JSON requests also use `Content-Type: application/json`. All routes require `auth:sanctum`.

## GET /devices

No query or request body is consumed by the controller. Returns the caller's devices, never any other user's devices.

**200 response (illustrative values, exact field structure):**
```json
{"data":[{"id":12,"platform":"android","name":"Pixel","push_enabled":true,"push_label":"<localized label>","push_hint":"<localized hint>"}]}
```

| Response field | Type | Meaning |
|---|---|---|
| `data` | array | Devices belonging to authenticated user |
| `data[].id` | integer or null | Device identifier |
| `data[].platform` | `ios` / `android` / `web` | Registered platform |
| `data[].name` | string | Device display name |
| `data[].push_enabled` | boolean | Push preference for installation |
| `data[].push_label` | string | Localized UI label |
| `data[].push_hint` | string | Localized UI helper text |

## POST /devices

| Request field | Type | Required | Validation |
|---|---|---|---|
| `platform` | string enum | Yes | Exactly `ios`, `android`, or `web` |
| `token` | string | Yes | Maximum 512 characters |
| `name` | string or null | No | Maximum 120 characters |
| `push_enabled` | boolean | No | Optional; omitted means application decides default |

**Example request:**
```json
{"platform":"android","token":"<FCM-token>","name":"Pixel","push_enabled":true}
```

**200 response (source-verified shape; illustrative values):**
```json
{"data":{"id":12,"platform":"android","name":"Pixel","push_enabled":true,"push_label":"<localized label>","push_hint":"<localized hint>"}}
```

The `token` is intentionally **never echoed**.

## PATCH /devices/{id}

| Input | Type | Required | Validation |
|---|---|---|---|
| Path `id` | integer | Yes | Numeric route constraint |
| Body `push_enabled` | boolean | Yes | `required`, `boolean` |

**Request:** `{"push_enabled":false}`

**200 response (illustrative values):**
```json
{"data":{"id":12,"platform":"android","name":"Pixel","push_enabled":false,"push_label":"<localized label>","push_hint":"<localized hint>","message":"<localized push-off message>"}}
```

**404** if the device does not belong to the caller or does not exist. Disabling push does not disable in-app notifications.

## DELETE /devices/{id}

Path `id`: required numeric integer. No request body. **204 No Content** on success. **404** for missing or non-owned device IDs. Client should remove the local device record only after success.
