Register this browser

PUT /me/push/devices

Register this browser, or the Manifold app on this phone, for push to the caller, with the token the push service gave it (Firebase's getToken), what the caller calls it (label), what it is (platform: web, ios or android — the app's are shown by the phone itself) and where the admin is mounted in it (base: "" on its own host, /admin in the Manifold app).

Push goes only to the organization's own people: a device is registered by a signed-in person and belongs to them, never to an app or a background run (403 PushNeedsPerson). Appends notifications.push-device-registered. Idempotent by state: the token is the device, so registering it again appends nothing unless its label, its platform, its place or its person changed, or it was last seen more than a day ago — which is how last-seen moves; a token another person registered becomes the caller's.

Access

Requires a signed-in session: a person's own devices and preferences: the route reads and changes only the caller's

How scopes come from roles: Scopes and roles. Getting a token: Authentication and app tokens.

Retries

Idempotent by state: the token is the device, so registering it again appends nothing unless its label, its platform, its place or its person changed, or it was last seen more than a day ago — which is how last-seen moves; a token another person registered becomes the caller's.

Why every write carries a key: Idempotency and retries.

Facts appended

notifications.push-device-registered

What a fact is: Facts and the journal.

AI agent tool

No agent tool. A device is the browser a person allowed to show notifications, registered by the admin with the push service's token; an agent has no such token.

Connecting an agent: AI agents.

Example

curl

curl -X PUT 'https://notifications.getmanifold.io/me/push/devices' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "fGq2k8x0TcS:APA91bHqv7oNfake-token-for-the-example",
  "label": "Sam'\''s iPhone",
  "platform": "ios",
  "base": "/admin"
}'

JavaScript (fetch)

const response = await fetch("https://notifications.getmanifold.io/me/push/devices", {
  method: "PUT",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "token": "fGq2k8x0TcS:APA91bHqv7oNfake-token-for-the-example",
    "label": "Sam's iPhone",
    "platform": "ios",
    "base": "/admin"
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();

Request body · application/json

{
  "token": "fGq2k8x0TcS:APA91bHqv7oNfake-token-for-the-example",
  "label": "Sam's iPhone",
  "platform": "ios",
  "base": "/admin"
}

Response · 200 · application/json

{
  "id": "pdv_01a15c20-4d5e-7f6a-8b9c-0d1e2f3a4b5c",
  "label": "Sam's iPhone",
  "platform": "ios",
  "base": "/admin",
  "registeredAt": "2026-10-29T01:12:00.000Z",
  "lastSeenAt": "2026-10-29T01:12:00.000Z"
}

The panel writes this call in other languages. It does not send it: Manifold's APIs do not take calls from a web page on another site, so run the call from your own code or terminal. The whole API as OpenAPI: notifications-manager.openapi.json. Base URL https://notifications.getmanifold.io.

Errors

Every refusal is a status and a JSON body whose _tag names it. A refused call changes nothing.

`401`

Refusal	What it means	What to do
`Unauthorized` reason	The token is missing, expired or not one Manifold issued.	Get a fresh token and send the call again.
`TokenAlreadyUsed` tokenId	A single-use app token was already spent.	Mint a new token for this call.

`402`

Refusal	What it means	What to do
`SubscriptionRequired` status	The organization's subscription has lapsed, so writes are refused.	An owner settles billing. Reads still work meanwhile.

`403`

Refusal	What it means	What to do
`PushNeedsPerson` reason	The request was refused. `reason` says why.	The caller may not do this. Use a token whose roles allow it.
`TenantRequired` userId	The token names no organization.	Choose the organization, then get a new token.
`ScopeRequired` required	The token's roles do not grant the scope this call needs.	Ask an owner or admin for a role that grants it.

`409`

Refusal	What it means	What to do
`MirroredFromSource` source	This area is fed by your source system until the organization goes live.	Make the change in the source system, or go live first.

`503`

Refusal	What it means	What to do
`RequestLogUnavailable` tokenId, reason	The service could not record the request, so it did nothing.	Send the same request again shortly.

How refusals work everywhere: Errors.