Skip to content

Upload an instance logo

POST
/admin/system/appearance/logo

Stores a raster image as the active logo and returns the updated appearance settings.

You need system.appearance.write or system.admin for the whole install. Without one you get 403, and signed-out callers get 401. The image isn’t read until that check passes.

Send the raw image bytes, not multipart form data. The server ignores the declared content type and works it out from the image. PNG, JPEG, GIF and WebP are accepted; SVG isn’t. The file can be at most 2 MiB, both dimensions must be between 16 and 1024 pixels inclusive, and the image must decode. The bytes are stored as sent, with no resizing, re-encoding or metadata stripping. An invalid image, one outside these limits, or a server with no storage configured gets a JSON 400; a failure reading the body or storing the image gets a plain-text 500.

The image is stored under its SHA-256 hash and pinned for appearance use. Uploading the same bytes again reuses the stored object and moves that logo to the front of the list. That reuse doesn’t check for or restore missing backend bytes, so a successful re-upload can still return an unavailable entry.

The new logo goes to the front of logo_history, which keeps up to five distinct entries; a sixth distinct image pushes out the oldest. Releasing the pin on a pushed-out image is best-effort, so a 200 doesn’t prove it was released. Stored bytes aren’t deleted; the storage garbage collector isn’t implemented. A listed logo’s versioned URL is public, active or not; fetching it still depends on its bytes being available.

Storage and settings changes aren’t one transaction. A later JSON 400 can leave the uploaded object and its pin behind, and a failed readback can return a plain-text 500 after the logo has changed. Concurrent saves can lose choices or leave pins out of step with the list. The response is a fresh read of the settings, so it can include another request’s change. Auditing is attempted after that read and isn’t guaranteed.

string format: binary

The appearance settings, read again after the upload.

Saved install-wide font and logo settings. The admin operations return the font choices, the active logo and, when it isn’t empty, the recent-logo list. The public boot response uses the same schema, adds its four boot fields and leaves out the list. The font PATCH writes only the four font fields. Empty or unknown font IDs fall back to the frontend defaults, and a known font that doesn’t suit its slot falls back to the first suitable catalogue entry.

object
brand_font

Catalogue ID of the brand and hero font. Empty or unknown means Limelight in the current frontend. Left out of responses when empty; omitting it on PATCH, or sending null or an empty string, resets it.

string
display_font

Catalogue ID of the H1–H3 heading font. Empty or unknown means Inter in the current frontend, whatever the body font is. Left out of responses when empty; omitting it on PATCH, or sending null or an empty string, resets it.

string
body_font

Catalogue ID of the body and interface font. Empty or unknown means the system sans-serif stack. Left out of responses when empty; omitting it on PATCH, or sending null or an empty string, resets it.

string
mono_font

Catalogue ID of the font for code and tabular numbers. Empty or unknown means the system monospace stack. Left out of responses when empty; omitting it on PATCH, or sending null or an empty string, resets it.

string
site_name

The install’s display name, sent only on the public boot response. It’s Artist Alley when unset or when its settings can’t be read. Left out of the admin responses and ignored on PATCH; change it in the site settings.

string
Example
Artist Alley
demo_mode

Whether demo mode is on, sent only on the public boot response, even when false. Left out of the admin responses and ignored on PATCH. It only announces the mode; it doesn’t block writes itself.

boolean
visual_search_enabled

Public boot flag for showing reverse-image search, set from whether a visual provider was configured at startup. It doesn’t promise that a later search succeeds. Left out of the admin responses and ignored on PATCH.

boolean
public_mode_enabled

Public boot flag for anonymous browsing, read from the public-mode settings and false if that read fails. Left out of the admin responses and ignored on PATCH. Access rules are enforced separately.

boolean
logo_url

Versioned public URL of the selected logo from the list. Left out for the bundled default or when the selection isn’t in the list; its presence doesn’t prove the image is available. Ignored on the font PATCH. Upload or select a logo to change it; DELETE clears it.

string
Example
/api/v1/appearance/logo?v=9f2b1c4d5e6a
logo_width

Saved width of the selected logo, in pixels. Left out when no listed logo is selected, even while the bundled default is shown, and can be present when the image is unavailable. Ignored on PATCH.

integer
Example
512
logo_height

Saved height of the selected logo, in pixels. Left out when no listed logo is selected, and can be present when the image is unavailable. Ignored on PATCH.

integer
Example
512
logo_history

Recent logos in saved order, most recently chosen first; writes keep at most five. Left out when empty and always left out of the public boot response. The default mark is never an entry. Ignored on the font PATCH, which carries the old list over only if it can read it. After failures or concurrent writes, pins and availability can drift from this list.

Array<object>

One recent logo: the metadata saved at upload, plus whether it’s available and whether it’s active. It points to the original stored bytes; it doesn’t contain the image.

object
hash
required

SHA-256 hash of the uploaded bytes. Use it to select the logo, or as v on the public logo route, while the entry is in the list. It isn’t a fresh integrity check of the stored bytes.

string
Example
9f2b1c4d5e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c
url
required

Versioned public URL for this entry, active or not. It may fail to load when the entry is unavailable, and cached copies can outlive the entry’s removal from the list.

string
Example
/api/v1/appearance/logo?v=9f2b1c4d5e6a
content_type
required

MIME type worked out from the decoded upload, not the client’s header, and saved with the entry.

string
Example
image/png
width
required

Image width in pixels, saved at upload time.

integer
Example
512
height
required

Image height in pixels, saved at upload time.

integer
Example
512
size_bytes
required

Size of the original uploaded file in bytes, saved at upload time.

integer format: int64
Example
18244
available
required

True when the storage metadata check succeeded while this response was built. False on any check error, or when there’s no storage backend. It isn’t a download or integrity check and doesn’t promise a later fetch will work. When it’s false, clients must clearly show that the logo is unavailable and must not offer it for selection.

boolean
Example
true
active
required

True when this hash matches the saved active selection. It can be true while available is false.

boolean

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed