Claim the instance
Creates the one owner using a machine-issued setup code or setup-only browser session. A claimed instance never reopens setup. A claim from the instance's own origin, which the setup page sends, also signs the owner in with a session cookie.
X-Marfa-Instance-Id?stringThe ID of the instance you expect, as GET / returns it. If another instance answers at this address, Marfa returns 409 instance_changed and doesn't write. Leave it out to send the request to whichever instance answers.
^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$application/json- body
username*stringThe username the owner signs in with: 1 to 64 letters a to z, numbers, dots, dashes and underscores. Marfa stores it in lowercase, with spaces at each end trimmed.
length <= 64password*stringPassword for the new owner.
name?stringDisplay name. Defaults to the username when omitted or blank.
length <= 200email?stringThe owner's email address. It plays no part in signing in. Marfa stores it in lowercase, with spaces at each end trimmed.
emaillength <= 254code?stringMachine-issued setup code. Omit when using a setup-only browser session.
The new owner can sign in. A claim from the instance's own origin also sets the owner session cookie, unless the sign-in that follows the claim fails. A claim with no Origin header, such as a script's, sets none.
application/json- response
The single owner of the instance.
id*stringUnique identifier for the owner.
username*stringThe username the owner signs in with.
email*|The owner's email address, or null when none is set. It plays no part in signing in.
name*stringDisplay name of the owner.
avatar*|The address of the owner's avatar on this instance, or null when none is set. Fetch it with GET /profile/avatar.
created_at*stringWhen the owner was created, in UTC.
Owner details are invalid, or the body has a field this endpoint doesn't take.
application/json- response
An error response.
error*What went wrong.
Setup proof is invalid, expired, or replaced.
application/json- response
An error response.
error*What went wrong.
The browser origin or transport is not permitted.
application/json- response
An error response.
error*What went wrong.
request_timeout: the request body didn't arrive whole within 180 seconds. Nothing changed, and Marfa closed the connection. Send the request again. A body larger than about 21 MiB can't arrive in that time over a 1 Mbit/s link, so send it in smaller requests.
application/json- response
An error response.
error*What went wrong.
The instance has already been claimed.
application/json- response
An error response.
error*What went wrong.
contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.
application/json- response
An error response.
error*What went wrong.
request_too_large: the request body is larger than this instance accepts.
application/json- response
An error response.
error*What went wrong.
The address has used its setup-code attempts.
application/json- response
An error response.
error*What went wrong.
internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.
application/json- response
An error response.
error*What went wrong.
curl -X POST 'http://localhost:8600/owner' \ -H 'Content-Type: application/json' \ -d '{ "username": "string", "password": "string"}'{ "id": "01926a3c-4b1d-7e52-9a8f-3c5d7e1b2a40", "username": "alex", "email": "alex@example.com", "name": "Alex Example", "avatar": null, "created_at": "2026-10-03T09:30:00.000Z"}