Users

All endpoints operate on the authenticated user (me is implicit — the session token identifies the user).

Endpoints

Method	Path	Description
GET	`/client/users/me`	Current user profile. Auto-backfills `timezone` from request headers.
PATCH	`/client/users/me`	Update `display_name`, `avatar_url`, `properties`, and/or `timezone`.
POST	`/client/users/me/push-token`	Register a push token (upsert on `token`).
DELETE	`/client/users/me/push-token`	Mark a token inactive.

GET /client/users/me

Response 200

{
  "data": {
    "id": "…",
    "email": "…",
    "display_name": "…",
    "avatar_url": "…",
    "external_id": "…",
    "anonymous_id": "anon_…",
    "auth_providers": [{ "provider": "apple", "provider_id": "…" }],
    "properties": {},
    "timezone": "America/New_York",
    "first_seen_at": "…",
    "last_seen_at": "…"
  }
}

Auto-backfill of `timezone`

If timezone is NULL for the user and the request carries one of the following headers, the API stores the header value and returns it in the response:

Time-Zone (RFC 7231).
X-Amba-Timezone (Amba SDK convention; preferred when both are present).

A non-null existing timezone is never overwritten by header detection — explicit user preference always wins. Invalid IANA names are ignored.

Errors

404 NOT_FOUND.
500 FETCH_FAILED.

Try it:

GET/client/users/me

client auth

curl -X GET 'https://api.amba.dev/v1/client/users/me'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/client/users/me' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

PATCH /client/users/me

Only these keys are honored: display_name, avatar_url, properties, timezone. Other keys are silently ignored.

timezone must be a valid IANA name (e.g. America/New_York, Europe/London, UTC). Validated by Intl.DateTimeFormat; bogus zones (or explicit null) are rejected with 400 INVALID_TIMEZONE. Set this once you know the user's zone — it powers the delivery_mode='local_time' push feature so 09:00 reminders fire at 09:00 in the user's actual time.

Request

{ "display_name": "Ada", "properties": { "theme": "dark" }, "timezone": "America/New_York" }

Response 200

Updated user row (same shape as GET /me).

Errors

400 INVALID_INPUT — no updatable fields provided.
400 INVALID_TIMEZONE — timezone is not a valid IANA name.
404 NOT_FOUND.
500 UPDATE_FAILED.

Try it:

PATCH/client/users/me

client auth

curl -X PATCH 'https://api.amba.dev/v1/client/users/me' \
  -H 'Content-Type: application/json' \
  -d '{
  "display_name": "Ada",
  "properties": {
    "theme": "dark"
  }
}'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X PATCH '${BASE_URL}/client/users/me' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{"display_name":"Ada","properties":{"theme":"dark"}}'

POST /client/users/me/push-token

Register a device push token. Upsert by token — re-registering the same device token updates app_user_id, platform, and reactivates it.

Request

Field	Type	Required
`token`	string	yes
`platform`	`"ios" \| "android"`	yes

provider is derived automatically (ios → apns, android → fcm).

Response 200

{
  "data": {
    "id": "…",
    "app_user_id": "…",
    "token": "…",
    "platform": "ios",
    "provider": "apns",
    "is_active": true
  }
}

Errors

500 REGISTER_FAILED.

Try it:

POST/client/users/me/push-token

client auth

curl -X POST 'https://api.amba.dev/v1/client/users/me/push-token'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/users/me/push-token' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /client/users/me/push-token

Soft-delete: sets is_active = false.

Request

Field	Type	Required
`token`	string	yes

Response 200

{ "data": { "unregistered": true } }

Errors

500 UNREGISTER_FAILED.

Try it:

DELETE/client/users/me/push-token

client auth

curl -X DELETE 'https://api.amba.dev/v1/client/users/me/push-token'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X DELETE '${BASE_URL}/client/users/me/push-token' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

On this page