User Preferences

The User Preferences endpoint stores per-user UI state — which servers you've pinned, your sidebar grouping choice, mobile-app preferences, and other per-user settings the Console and any mobile app share. Use it to keep preferences in sync across devices or to read them from a third-party integration.

Namespaces

Preferences are organised by namespace. Only two namespaces are accepted by the API:

console.* — preferences used by the web Console
mobile.* — preferences used by the Depfloy mobile app

Writes outside these namespaces are rejected with 422 Unprocessable Entity.

GET/api/v1/me/preferences

Read all preferences

Returns every preference currently stored for the authenticated user, grouped by namespace.

Request

GET

/api/v1/me/preferences

curl https://app.depfloy.com/api/v1/me/preferences \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json"

Response

{
  "preferences": {
    "console": {
      "sidebar": {
        "group_by": "environment",
        "collapsed_groups": ["dev"]
      },
      "pinned_servers": [183009, 183010]
    },
    "mobile": {
      "notifications": {
        "push_enabled": true
      }
    }
  }
}

PATCH/api/v1/me/preferences

Update preferences

Patch the current user's preferences. The request body is deep-merged with the existing state — you only need to send the fields you want to change. Keys you don't include are preserved.

To delete a key, set it to null in the patch.

Required attributes

Name
preferences
Type
object
required
*
Description
An object keyed by namespace (console, mobile). Each namespace's value is merged into the existing one.

Limits

Total stored preferences size is capped at 16 KB. Requests that would exceed the cap are rejected with 422.
Last-write-wins: there's no per-key locking. If two clients update the same key at nearly the same time, the later request wins.

Request

PATCH

/api/v1/me/preferences

curl -X PATCH https://app.depfloy.com/api/v1/me/preferences \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "console": {
        "sidebar": {
          "group_by": "server_type"
        }
      }
    }
  }'

Response

{
  "preferences": {
    "console": {
      "sidebar": {
        "group_by": "server_type",
        "collapsed_groups": ["dev"]
      },
      "pinned_servers": [183009, 183010]
    },
    "mobile": {
      "notifications": {
        "push_enabled": true
      }
    }
  }
}