Update Appearance settings

PUT

/api/v1/appearance

const url = 'https://example.com/api/v1/appearance';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"auto_scheme":{"mode":"system"},"background":{"dark":{"kind":"theme"},"light":{"kind":"theme"}},"background_assignment":{"background":{"kind":"theme"},"family":"paper","scheme":"light"},"backgrounds":"example","fonts":{"display":"bricolage-grotesque","mono":"maple-mono","ui":"google-sans"},"initialize_auto_scheme":{"mode":"system"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url https://example.com/api/v1/appearance \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "auto_scheme": { "mode": "system" }, "background": { "dark": { "kind": "theme" }, "light": { "kind": "theme" } }, "background_assignment": { "background": { "kind": "theme" }, "family": "paper", "scheme": "light" }, "backgrounds": "example", "fonts": { "display": "bricolage-grotesque", "mono": "maple-mono", "ui": "google-sans" }, "initialize_auto_scheme": { "mode": "system" } }'

Updates the Appearance settings. It requires a signed-in User with the data scope. It can return 400 if the request is invalid, 401 if the session is missing or expired, 403 if access is denied, 404 if the requested item does not exist, 409 if the request conflicts with the current state and 507 if there is not enough storage space. Route: /api/v1/appearance. Inputs: . Do not automatically replay this operation after an uncertain result.

Authorizations

installationBearer
browserSession

Request Body^required

application/json

Assignment of one or both per-User appearance preferences.

object

auto_scheme

One of:

object
null

The User’s colour scheme. Location has one home in Location settings (§47).

object

mode

required

A persistent colour scheme choice.

string

Allowed values: system auto light dark

background

One of:

object
null

Legacy light/dark pair accepted during the migration window.

object

dark

One of:

object
null

One of:

Use the selected theme’s static mesh gradient.

object

kind

required

string

Allowed values: theme

light

required

One of:

Use the selected theme’s static mesh gradient.

object

kind

required

string

Allowed values: theme

background_assignment

One of:

object
null

One update that preserves every other family and scheme pick.

object

background

required

One of:

Use the selected theme’s static mesh gradient.

object

kind

required

string

Allowed values: theme

family

required

Stable family keys used for backgrounds shared between devices.

string

Allowed values: paper meridian bloom mono solarized catppuccin rose-pine ayu github one tokyo-night gruvbox everforest kanagawa dracula nord

scheme

required

Family and scheme target for a server-downloaded Unsplash photo.

string

Allowed values: light dark

backgrounds

Per-family light and dark backgrounds.

object | null

fonts

One of:

object
null

The three type roles that a User can choose in Settings → Appearance.

object

display

required

Display face ids are stable settings values, not font file names.

string

Allowed values: bricolage-grotesque newsreader fraunces literata source-serif-4 roboto-serif playfair-display

mono

required

Mono face ids are stable settings values, not font file names.

string

Allowed values: maple-mono spline-sans-mono jetbrains-mono system

required

UI face ids are stable settings values, not font file names.

string

Allowed values: google-sans inter system

initialize_auto_scheme

One of:

object
null

Initialize from an old Installation’s local choice only when the User has no saved scheme (#507). Use auto_scheme for an explicit selection.

object

mode

required

A persistent colour scheme choice.

string

Allowed values: system auto light dark

Responses

200

application/json

Readable appearance state and instance capabilities.

object

auto_scheme

One of:

object
null

None means no Installation has migrated a colour scheme yet.

object

mode

required

A persistent colour scheme choice.

string

Allowed values: system auto light dark

background

required

The old light/dark pair, present only until the client writes its family-keyed migration. Kept as a read bridge for one release.

object

dark

One of:

object
null

One of:

Use the selected theme’s static mesh gradient.

object

kind

required

string

Allowed values: theme

light

required

One of:

Use the selected theme’s static mesh gradient.

object

kind

required

string

Allowed values: theme

backgrounds

required

Background choices by theme family. A missing family uses its theme.

object

key

additional properties

The two backgrounds saved for a family.

object

dark

required

One of:

Use the selected theme’s static mesh gradient.

object

kind

required

string

Allowed values: theme

light

required

One of:

Use the selected theme’s static mesh gradient.

object

kind

required

string

Allowed values: theme

capabilities

required

Feature availability for optional appearance sources.

object

unsplash_available

required

boolean

fonts

required

The three type roles that a User can choose in Settings → Appearance.

object

display

required

Display face ids are stable settings values, not font file names.

string

Allowed values: bricolage-grotesque newsreader fraunces literata source-serif-4 roboto-serif playfair-display

mono

required

Mono face ids are stable settings values, not font file names.

string

Allowed values: maple-mono spline-sans-mono jetbrains-mono system

required

UI face ids are stable settings values, not font file names.

string

Allowed values: google-sans inter system

Example

{
  "auto_scheme": {
    "mode": "system"
  },
  "background": {
    "dark": {
      "kind": "theme"
    },
    "light": {
      "kind": "theme"
    }
  },
  "backgrounds": {
    "additionalProperty": {
      "dark": {
        "kind": "theme"
      },
      "light": {
        "kind": "theme"
      }
    }
  },
  "fonts": {
    "display": "bricolage-grotesque",
    "mono": "maple-mono",
    "ui": "google-sans"
  }
}

400

application/json

The standard API error response: { "error": { ... } }.

object

error

required

Error details.

object

code

required

Stable machine-readable code.

string

Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable

details

One of:

object
null

Optional field or operation details.

object

key

additional properties

string

message

required

Safe text for logs or a user-facing error message.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

401

application/json

The standard API error response: { "error": { ... } }.

object

error

required

Error details.

object

code

required

Stable machine-readable code.

string

Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable

details

One of:

object
null

Optional field or operation details.

object

key

additional properties

string

message

required

Safe text for logs or a user-facing error message.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

403

application/json

The standard API error response: { "error": { ... } }.

object

error

required

Error details.

object

code

required

Stable machine-readable code.

string

Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable

details

One of:

object
null

Optional field or operation details.

object

key

additional properties

string

message

required

Safe text for logs or a user-facing error message.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

404

application/json

The standard API error response: { "error": { ... } }.

object

error

required

Error details.

object

code

required

Stable machine-readable code.

string

Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable

details

One of:

object
null

Optional field or operation details.

object

key

additional properties

string

message

required

Safe text for logs or a user-facing error message.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

409

application/json

The standard API error response: { "error": { ... } }.

object

error

required

Error details.

object

code

required

Stable machine-readable code.

string

Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable

details

One of:

object
null

Optional field or operation details.

object

key

additional properties

string

message

required

Safe text for logs or a user-facing error message.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

507

application/json

The standard API error response: { "error": { ... } }.

object

error

required

Error details.

object

code

required

Stable machine-readable code.

string

Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable

details

One of:

object
null

Optional field or operation details.

object

key

additional properties

string

message

required

Safe text for logs or a user-facing error message.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

Update Appearance settings

Authorizations

Request Bodyrequired

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

409

Example

507

Example

Request Body^required