Skip to content
calternal docs

Select a background image

POST
/api/v1/appearance/unsplash/{photo_id}
curl --request POST \
  --url https://example.com/api/v1/appearance/unsplash/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "family": "paper", "scheme": "light" }'

Selects a background image. 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, 429 if the request limit is reached and 503 if the service is temporarily unavailable. Route: /api/v1/appearance/unsplash/{photo_id}. Inputs: photo_id. Do not automatically replay this operation after an uncertain result.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
photo_id
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
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

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

Readable appearance state and instance capabilities.

object
auto_scheme
One of:

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:
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
ui
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

Section titled “400”
Media typeapplication/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:

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

Section titled “404”
Media typeapplication/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:

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"
  }
}

429

Section titled “429”
Media typeapplication/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:

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"
  }
}

503

Section titled “503”
Media typeapplication/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:

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"
  }
}