Save appearance fonts
PATCH /admin/system/appearance
Replaces all four saved font choices and returns the resulting appearance settings.
You need system.appearance.write or system.admin for the whole install; read permission isn’t enough, and a permission held only for a team doesn’t count. A body that can’t be decoded gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401 and callers without the permission 403.
Send every font choice you want to keep. An omitted, null or empty font field resets that slot, and {} or null resets all four. Any other field is ignored. Font IDs are saved exactly as sent, up to 64 UTF-8 bytes each. The server doesn’t check them against the font catalogue or whether a font suits its slot; the frontend resolves each choice and falls back when needed.
The active logo and recent-logo list are carried over from the previous settings. If reading those fails, the save goes ahead without them, so a successful save can clear the logo and the list while leaving their storage pins behind.
There’s no version check, so concurrent font and logo writes can overwrite each other. The response shows the settings this request saved, with fresh availability checks, not a new read of the latest configuration. Validation and save errors, database errors included, get a JSON 400, and a save error doesn’t mean nothing was written. Auditing is attempted after the save and isn’t guaranteed.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”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
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.
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.
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.
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.
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.
Example
Artist AlleyWhether 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.
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.
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.
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.
Example
/api/v1/appearance/logo?v=9f2b1c4d5e6aSaved 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.
Example
512Saved 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.
Example
512Recent 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.
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
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.
Example
9f2b1c4d5e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2cVersioned 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.
Example
/api/v1/appearance/logo?v=9f2b1c4d5e6aMIME type worked out from the decoded upload, not the client’s header, and saved with the entry.
Example
image/pngImage width in pixels, saved at upload time.
Example
512Image height in pixels, saved at upload time.
Example
512Size of the original uploaded file in bytes, saved at upload time.
Example
18244True 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.
Example
trueTrue when this hash matches the saved active selection. It can be true while available is false.
Responses
Section titled “ Responses ”The appearance settings this request saved.
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
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.
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.
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.
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.
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.
Example
Artist AlleyWhether 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.
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.
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.
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.
Example
/api/v1/appearance/logo?v=9f2b1c4d5e6aSaved 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.
Example
512Saved 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.
Example
512Recent 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.
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
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.
Example
9f2b1c4d5e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2cVersioned 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.
Example
/api/v1/appearance/logo?v=9f2b1c4d5e6aMIME type worked out from the decoded upload, not the client’s header, and saved with the entry.
Example
image/pngImage width in pixels, saved at upload time.
Example
512Image height in pixels, saved at upload time.
Example
512Size of the original uploaded file in bytes, saved at upload time.
Example
18244True 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.
Example
trueTrue when this hash matches the saved active selection. It can be true while available is false.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completed