> ## Documentation Index
> Fetch the complete documentation index at: https://285e39fd5e337e58f16290.sightscreen.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Devices

> Multi-device registration, push tokens, and notification endpoints.

## Endpoint reference

| Method   | Route                                | Auth  | Purpose                         |
| -------- | ------------------------------------ | ----- | ------------------------------- |
| `POST`   | `/devices`                           | User  | Register or update a device     |
| `DELETE` | `/devices/:deviceToken`              | User  | Unregister a device             |
| `POST`   | `/devices/push-to-start-token`       | User  | Register push-to-start token    |
| `POST`   | `/admin/notifications/push`          | Admin | Send a manual push notification |
| `GET`    | `/admin/notifications/users`         | Admin | List users with push tokens     |
| `GET`    | `/admin/notifications/subscriptions` | Admin | List notification subscriptions |

***

## Device registration

<Note>
  See the [Device registration](/business-flows/device-registration) business flow for the full end-to-end journey.
</Note>

### POST /devices `User`

Register or update a device for push notifications (APNs). Sightscreen supports **multi-device** -- a user can have multiple devices registered simultaneously. There is no single-device enforcement.

<ParamField body="deviceToken" type="string" required>
  The APNs device token from the iOS app.
</ParamField>

<ParamField body="platform" type="string" required>
  Device platform. Currently only `ios` is supported.
</ParamField>

<ParamField body="deviceId" type="string" required>
  The `identifierForVendor` from iOS. Used to uniquely identify the physical device across token rotations.
</ParamField>

<ParamField body="osVersion" type="string">
  The iOS version running on the device (e.g., `18.3.1`). Stored for diagnostics and compatibility targeting.
</ParamField>

<ParamField body="appVersion" type="string">
  The Sightscreen app version (e.g., `2.1.0`). Stored for diagnostics and feature gating.
</ParamField>

<Tabs>
  <Tab title="Request">
    ```json theme={null}
    {
      "deviceToken": "abc123def456...",
      "platform": "ios",
      "deviceId": "E621E1F8-C36C-495A-93FC-0C247A3E6E5F",
      "osVersion": "18.3.1",
      "appVersion": "2.1.0"
    }
    ```
  </Tab>

  <Tab title="Response (200)">
    ```json theme={null}
    {
      "ok": true
    }
    ```
  </Tab>
</Tabs>

<Note>
  If a device with the same `deviceId` already exists for this user, the record is updated (new token, updated osVersion/appVersion, refreshed `lastSeenAt`). Otherwise a new device record is created.
</Note>

### Device TTL

Device records have a TTL of **90 days** from the `lastSeenAt` timestamp. Devices that have not called `POST /devices` within 90 days are automatically expired by DynamoDB TTL. This prevents stale tokens from accumulating.

### DELETE /devices/:deviceToken `User`

Unregister a device. Call this on logout or when the user disables notifications.

<ParamField path="deviceToken" type="string" required>
  The APNs device token to remove.
</ParamField>

### POST /devices/push-to-start-token `User`

Register a push-to-start token for iOS Live Activities. This token allows the backend to start a Live Activity on the device without the app being in the foreground.

<ParamField body="pushToStartToken" type="string" required>
  The push-to-start token from the iOS app.
</ParamField>

<ParamField body="matchId" type="string" required>
  The match this token is associated with.
</ParamField>

***

## Admin notifications

### POST /admin/notifications/push `Admin`

Send a manual push notification to one or more users.

<ParamField body="title" type="string" required>
  Notification title.
</ParamField>

<ParamField body="body" type="string" required>
  Notification body text.
</ParamField>

<ParamField body="userIds" type="string[]">
  Target specific users. Omit to broadcast to all users with push tokens.
</ParamField>

<ParamField body="matchId" type="string">
  Associate the notification with a match (for deep linking).
</ParamField>

<Warning>
  Broadcasting to all users sends to every registered device across all of a user's devices. Use with care.
</Warning>

### GET /admin/notifications/users `Admin`

List users who have registered push notification tokens.

### GET /admin/notifications/subscriptions `Admin`

List all active notification subscriptions (match follows with push enabled).