User API

Endpoints that operate on the user record behind the request: reading it, erasing it, and registering a device for push notifications.

The user’s long-term agent memory has its own page — see Memory API — as do the in-app navigation hints, see Navigation API.

GET /api/user

Return the user record of the current request.

Query Parameters

Parameter Required Type Description

deviceRef

No

String

Fallback used when the request carries no authenticated identity: the device with this ref is looked up (and created if unknown) and its associated anonymous user is returned.

Response

Field Type Description

id

UUID string

User identifier — the userId referenced by sessions and memory.

name

String | null

Display name, when known.

created

Timestamp

When the user record was created.

 
{
  "id": "5c8a0f12-7d34-4e56-9a1b-2c3d4e5f6a7b",
  "name": "Alex Novak",
  "created": "2026-04-17T08:11:03.442Z"
}

An anonymous user resolved through deviceRef has "name": null. Responds 404 when neither an authenticated user nor a deviceRef resolves to a user.

DELETE /api/user

Erase the current user: purges the user’s session data, deletes their memory and removes the user record.

Query Parameters

Parameter Required Type Description

deviceRef

No

String

Identifies the user when the request is not authenticated, exactly as for GET /api/user.

Takes no request body. This is the endpoint to wire to a "delete my data" action; it is irreversible.

POST /api/user/fcmToken

Register a Firebase Cloud Messaging token so the platform can deliver push notifications to the device. Requires the consumer role. Takes no path or query parameters.

Request Body

Field Required Type Description

token

Yes

String

FCM registration token.

info

No

String

Free-text device description, shown when managing devices. Defaults to an empty string.

deviceId

No

String

Client-side device identifier. Defaults to an empty string.

 
{
  "token": "fZ1x…9Qk",
  "info": "iPhone 15 Pro",
  "deviceId": "client:AA-BB-CC-DD-EE-FF"
}

Response

The number of tokens registered for the user after the call, as a plain integer. A token equal to an already registered one replaces it rather than being added twice.