Skip to content

Update the site name and address

PATCH
/admin/system/site

Saves the site’s display name, its base URL, or both, and returns the result.

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 isn’t valid JSON, or has a field of the wrong type, gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401 and callers without the permission 403.

Each field is merged with the saved settings:

  • name: an empty, null or missing name keeps the saved one. Any other value replaces it as sent, without trimming, so a name of only spaces is saved; the declared length limits aren’t checked.
  • base_url: leaving it out or sending null keeps the saved one. Any string replaces it as sent, and an empty string clears it. The value isn’t checked, and the server doesn’t test that the address works.

Unknown fields are ignored. The whole site setting is then written in one step, and the response shows what this call wrote, not a fresh read. If the saved settings can’t be read first, the save still goes ahead from empty settings, so a field you didn’t send can be cleared. Two saves made at the same time can overwrite each other: each starts from the settings it read. Server errors get a plain-text 500.

The name is shown to every visitor, signed in or not, and both values are used in emails and links. Pages already open keep the old name until they reload, and part of the server reads the values only when it starts, so a change can need a restart to reach everything. Changing the base URL doesn’t change links already sent.

object
name
required
string
>= 1 characters <= 100 characters
Example
Acme Art Reviews
base_url

Absolute URL the site is reachable at. Used to build outgoing links (e.g., password-reset emails). May be empty at install time and filled in later.

string
Example
https://art.example.com

The site settings as this call saved them.

object
name
required
string
>= 1 characters <= 100 characters
Example
Acme Art Reviews
base_url

Absolute URL the site is reachable at. Used to build outgoing links (e.g., password-reset emails). May be empty at install time and filled in later.

string
Example
https://art.example.com

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