Complete first-run setup
POST /setup/complete
Completes first-run setup: creates an administrator account and saves the site name, the site address and the email settings in one transaction, so either all of it is saved or none of it is.
No sign-in is needed. Setup is open while the administrator count
that getSetupStatus describes is zero, and while it is open anyone
who can reach the server can call this and become its administrator;
there is no setup token. On a normal start the server sets up an
administrator itself, so setup is usually closed and the call gets
409.
The new account gets the Admin role for the whole install and a
federation key; setup then closes if the Admin role lists
system.admin. This call doesn’t sign you in: no session is
created, so sign in with the new account afterwards. The response
describes the account without its capabilities or preferences, with
auth_method set to session, capabilities_status set to
unavailable and mature_content_allowed set to true.
A body that can’t be decoded, such as one with a wrong type or an
email that isn’t a valid address, gets a plain-text 400, even when
setup is closed. Otherwise a closed setup gets 409. Then the fields
are checked, and a failed check gets 400 with the reason in error:
the username is trimmed and must be 1 to 50 bytes, and the password
at least 8 bytes. Only the bare email address is kept, without a
display name. A blank full name is left out. The site name is
trimmed and must be 1 to 100 bytes. base_url may be left out or
empty; any other value is trimmed and must then have a scheme and a
host (any scheme is accepted), and trailing slashes are removed.
Unknown fields are ignored.
If smtp is null or missing, empty email settings are saved,
replacing any saved before. Otherwise host and from_address are
trimmed, username and password are kept as sent, and
password_set is ignored. With an empty host, nothing else is
checked. With a host, encryption must be none, starttls or
tls, port 1 to 65535, and from_address a valid address. The
password is stored encrypted and never returned. Nothing is sent to
test the settings.
Two calls made at the same time while setup is open can both succeed and create two administrators, because each counts before the other’s account is saved. If both get past the count with the same username, one fails with a server error. A later call, including a retry after a lost response, gets 409 if setup has closed by then; if the count is still zero, it runs like a first call. Once a call is past those checks, a username another account already has, or an email or full name longer than 100 characters, fails as a server error. Server errors get a plain-text 500.
Request Body required
Section titled “Request Body required ”object
object
Trimmed; 1 to 50 bytes. It must not already belong to another account.
Example
adminAt least 8 bytes, used as given. It is never returned.
A valid address; only the bare address is kept, without a display name. At most 100 characters.
Example
admin@example.comOptional; trimmed, and left out when blank. At most 100 characters.
Example
Site Administratorobject
Example
Acme Art ReviewsAbsolute 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.
Example
https://art.example.comThe email settings, or null to save empty ones. Either way they replace any saved before.
object
Example
smtp.example.comExample
587Example
starttlsWrite-only. Provide to set or rotate the SMTP password;
omit (or send empty string) on PATCH to keep the current
value. The response never echoes this field — read
password_set instead to check whether one is on file.
Stored at rest encrypted via the AA_MASTER_KEY-backed
atrest package; never sent back to clients.
True when a password is currently stored. Set by the server on GET responses; ignored if sent on PATCH.
Example
ArtSite <noreply@example.com>Responses
Section titled “ Responses ”The new administrator account. You aren’t signed in; sign in with it to continue.
object
How this request was signed in: session for the session cookie, token for an API token.
The account’s preferred language, as a BCP 47 tag such as fr. Left
out when the account hasn’t chosen one; the client can then follow
the browser’s language.
The account’s saved theme. system means follow the device’s light
or dark setting. Left out when the account hasn’t chosen a theme,
and the client then uses its own default.
The account’s default browse settings: which feed tab opens first, the layout and the sort order. Left out when none are set. Treat them as starting values; a choice made on the device itself should win.
object
The feed tab the browse page opens on. Empty or unset means
latest.
The default browse layout, used when the operator has that layout turned on. Otherwise the app picks a default for the device from the layouts that are turned on.
The default sort order: newest posts first or oldest first.
Empty or unset means newest.
The account’s feed filter settings, included only when a filter is
turned on. GET /posts applies them itself; they’re here so a
client can explain why the feed looks different.
object
Whether GET /posts keeps placeholders for assets you can’t see.
It’s off by default: the feed drops those assets, and drops a post
altogether when it had assets and none are left, unless you wrote
it. Turn it on to keep every placeholder. Other endpoints, such as
GET /posts/{id}, don’t use this setting.
How the person has arranged the team and tag shortcuts in the browse page’s rail: which they’ve hidden and which they’ve moved to the front. Left out when they haven’t changed anything. The server doesn’t use it to filter posts; it’s for the client to apply to the rail.
object
Teams the person has hidden from the rail. Empty means none.
Followed teams the person has moved to the front, in that order. Other teams keep their usual order behind them. Empty means the server’s order.
Followed tags the person has hidden from the rail. Hiding a tag isn’t unfollowing it: its posts still reach the following feed.
Followed tags the person has moved to the front, in that order, with the rest behind them. Empty means the server’s order, most recently followed first.
The account’s mature-content setting, included only when the person
has opted in. Opting in isn’t enough on its own;
mature_content_allowed explains the rest.
object
Whether the account has opted in to mature content. Absent or
false means it hasn’t, which is the default.
Whether this instance allows mature content. It’s the operator’s
setting, not the account’s, and it’s always included. When it’s
false, don’t offer the opt-in. Ordinarily an account sees mature
content only when this is true and it has opted in. Two exceptions
hold even when it’s false: people still see their own mature
items, and system administrators see all of them. Neither exception
overrides the usual permission checks.
The account’s global capability codes, after its role, extra grants
and revocations are combined. It’s the same list GET /auth/me/capabilities returns. Capabilities that apply only within
a team aren’t included. Left out when capabilities_status is
unavailable.
Whether the capability list could be loaded for this response.
resolved means capabilities is complete, and an empty list means
the account has none. unavailable means the lookup failed:
capabilities is left out and tells you nothing about the account.
Treat that as an error you can retry, not as a lack of permission,
and don’t show controls that need a capability until you have a
resolved list.
Present when an admin is acting as this account through POST /admin/users/{ref}/impersonate. It gives the admin’s ref and
username, so a client can show who is really signed in.
object
Malformed request
object
Human-readable error summary
Example
the request could not be completedSetup is closed: the administrator count is above zero.
object
Human-readable error summary
Example
the request could not be completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed