Skip to content

Set a site-text override

PUT
/site-text/{key}

Saves one UI-text replacement for one language.

You need system.config.write or system.admin for the whole install; 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.

The server trims whitespace around the path key and language, and both must be nonempty. The key must match the build’s embedded English catalogue exactly, including case; once the other input checks pass, an unknown key gets 422 naming it. Language codes aren’t checked against the client’s supported locales. The current web client uses en, es and fr.

value is stored as sent, up to 4,096 UTF-8 bytes. Empty text is allowed and isn’t the same as deleting the override. The schema requires value, but leaving it out or sending null currently saves an empty string when the key and language are valid. A missing or null language fails the nonempty check. An empty body, malformed JSON or a field of the wrong type gets 400.

The response is the row the save returned, not rendered text. Other keys and languages are left alone. The server clears this app instance’s override cache and tries to notify other instances; a successful response doesn’t guarantee that every later read or open browser has refreshed. The web client that saved applies its draft locally.

There’s no version check. Concurrent saves to the same key and language can overwrite each other, and a concurrent revert can remove the row. Each key and language is stored as its own row.

key
required
string

The exact dotted key from the embedded English catalogue, for example nav.collections. Surrounding whitespace is trimmed.

Replacement text and language for the key in the request path.

object
language
required

Nonempty after trimming. The server accepts language strings beyond the client’s current en, es and fr; values are case-sensitive and aren’t normalized.

string
>= 1 characters
Example
en
value
required

Replacement text, stored untrimmed, up to 4,096 UTF-8 bytes. Empty text deliberately blanks the label. An omitted or null value currently becomes empty too, despite the schema requirement. To remove the override, use DELETE.

string
Example
Libraries

The saved override row, including its update timestamp when available.

One saved UI-text override, returned after a successful write.

object
key
required

The trimmed, case-sensitive dotted key this override replaces.

string
Example
nav.collections
language
required

The trimmed language string stored for this override. It isn’t validated or normalized as a supported locale.

string
Example
en
value
required

The stored replacement text, including an empty string when the label was blanked. The web translation resolver can fill in {name} placeholders; it doesn’t render this value as HTML.

string
Example
Libraries
updated_at

The row’s update timestamp, when available. Saving the same text again can update it.

string format: date-time

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

Request shape is valid but the action doesn’t apply (e.g. subtitles on a non-video/audio asset).

object
error
required

Human-readable error summary

string
Example
the request could not be completed