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.

AUTH Authorization: Bearer {API_KEY} Create a token →

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.

GET /api/v1/me/preferences Request
cURL
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 #

preferences object

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.
PATCH /api/v1/me/preferences Request
cURL
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
      }
    }
  }
}