Settings, Preferences and Devices

Each user has settings that follow them across browsers and devices: preferences for how the product looks and behaves, notification settings for what reaches them and where, and a registry of their devices. They are all personal, so every call acts on the signed-in user and nobody else's.

Preferences

A preference is a key and a JSON value, such as schema:action-menu-mode set to "grid". A preference has a scope, global (the default) or project. A project-scoped preference carries the project id as its scope id, so the same key can hold a different value in each project.

TaskCall
List all of your preferencesGET /preferences
Read or delete one by keyGET or DELETE /preferences/{key}
Set one or morePUT /preferences
Merge a batch from a clientPOST /preferences/sync

Sync is for clients that keep a local copy. Each item carries the client's updatedAt, and the merge is last-write-wins on that timestamp.

Notification settings

A notification setting decides whether a category of notification reaches you on a channel.

  • Categories: WORKFLOW, BACKLOG, KNOWLEDGE, SESSION, BRAINSTORMING, SCM, GOVERNANCE, ARTIFACT, NOTIFICATION and SYSTEM.
  • Channels: web (the in-app bell) and email.
  • Each setting has enabled and an optional minSeverity, the lowest severity you want to hear about on that channel.

GET /notification-settings returns every category and channel pair. A pair you have never changed shows the platform default and has isDefault: true; one you set shows isDefault: false. PUT /notification-settings upserts many at once, PUT /notification-settings/{category}/{channel} sets one, and DELETE on the same path resets that pair to the platform default.

Devices

A device registry tells Xema where you are signed in, per channel. POST /devices registers a device or updates one you already registered, with a channel, a client-generated deviceId and optional metadata. The record keeps when the device was last seen. GET /devices lists your devices and DELETE /devices/{deviceId} removes one.

Your inbox

  • GET /notifications lists your notifications (paged), and GET /notifications/unread returns the unread count and stats.
  • PATCH /notifications/{id}/read marks one read, and PATCH /notifications/read-all marks all of them. PATCH /notifications/{id}/dismiss dismisses one, which is permanent.
  • GET /questions lists questions waiting on you (approvals, choices, free-form answers and reviews), and GET /questions/badge returns the pending count for a badge.

Previous: ← Groups