---
title: "Subscribe a device to push notifications [write]"
method: POST
path: "/push-subscriptions"
tags: ["notifications"]
---

# Subscribe a device to push notifications \[write\]

`POST /push-subscriptions`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/push-subscriptions`
- Auth: HTTP bearer

From a browser, send what its `pushManager.subscribe()` returned. From the phone app, send `{ kind: "expo", token }` with the device token Expo issued. Subscribing the same device again keeps one subscription. Answers 403 `not_enabled` where push is not turned on, 400 for an endpoint that is not a browser push service's or a token that is not Expo's, and 503 `not_migrated` until the platform's push tables are in place.

## Request body

- object: A browser sends `endpoint` and `keys`; the phone app sends `kind` and `token`. One pair or the other, never both.
  - `endpoint` string: A browser push service's address. With `keys`.
  - `keys` object
    - `p256dh` string, required
    - `auth` string, required
  - `kind` 'expo': `expo`, for the phone app. With `token`.
  - `token` string: The device token Expo issued to this phone.

## Response `201`

Created

- object
  - `subscription` PushSubscription, required: One device the caller asked to be notified on. A browser's keys are never returned.
    - `id` string, required
    - `kind` 'web' | 'expo', required: `web` for a browser, `expo` for the phone app.
    - `endpoint` string, required: The push service's address for that browser, or the phone app's Expo device token.
    - `created_at` string, date-time, required
    - `last_seen_at` string, date-time, required: When that device last subscribed.

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/push-subscriptions/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)