Change the site's appearance

Only what is sent changes. Custom CSS loads after the theme, so it wins; it styles tokens like –site-accent and parts like [data-part=“hero”]. Admins and owners only.

PATCH/site/appearance

Authorization

AuthorizationBearer token · headerrequired

`MEDIAN_KEY` from Settings under API, or an MCP OAuth access token. A key acts as the organization; a token acts as the person who approved it.

Request body

application/json

themestring

Allowed:paper

schemestring

Allowed:systemlightdark

navigationstring

A bar across the top, a sidebar with each collection's articles under it, or a sidebar listing the collections alone. Sites that never set it get sidebar.

Allowed:topsidebartopics

accentstring | null

A hex color like #4f46e5, or null to use the theme's own.

cssstring

Replaces the whole stylesheet, up to 60,000 characters. An empty string removes it.

Responses

200The appearance, as it now reads.

themestring

Allowed:paper

schemestring

Allowed:systemlightdark

navigationstring

A bar across the top, a sidebar with each collection's articles under it, or a sidebar listing the collections alone.

Allowed:topsidebartopics

accentstring | null

A hex color, or null for the theme's own.

cssstring

The custom stylesheet. Empty when there is none.

400The request is malformed, and the message names the field.

errorobject

Show properties

codestring

messagestring

401The bearer token is missing, revoked, or expired.

errorobject

Show properties

codestring

messagestring

429Too many requests. Wait the seconds in `Retry-After`. Limits depend on the plan. See [rate limits](/api/errors-and-limits#rate-limits).

errorobject

Show properties

codestring

messagestring

Request

curl -X PATCH "https://api.median.sh/v1/site/appearance" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "theme": "paper",
  "scheme": "system",
  "navigation": "top",
  "accent": "string",
  "css": "string"
}'

const response = await fetch("https://api.median.sh/v1/site/appearance", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "theme": "paper",
  "scheme": "system",
  "navigation": "top",
  "accent": "string",
  "css": "string"
})
});

Response

{
  "theme": "paper",
  "scheme": "system",
  "navigation": "top",
  "accent": "string",
  "css": "string"
}