runSetup

POST

/setup

curl --request POST \
  --url http://localhost:8080/api/v1/setup \
  --header 'Content-Type: application/json' \
  --data '{ "householdName": "example", "username": "example", "displayName": "example", "password": "example", "locale": "en" }'

• Your Homestead (default port; replace with your address)

Creates the household and the owner. Only works while no household exists.

Request Body^required

Media typeapplication/json

object

householdName

required

string

>= 1 characters <= 60 characters

username

required

string

/^[a-zA-Z0-9_.-]{3,32}$/

displayName

required

string

>= 1 characters <= 60 characters

password

required

string

>= 8 characters <= 200 characters

locale

required

string

Allowed values: en zh-Hans th

Responses

201

Household created. Owner is logged in (web cookie set).

Media typeapplication/json

object

member

required

object

id

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

username

required

string

displayName

required

string

role

required

string

Allowed values: owner member viewer

locale

One of:

string

string

Allowed values: en zh-Hans th

null

null

theme

required

string

Allowed values: system light dark

textScale

required

number

>= 1 <= 1.6

reducedMotion

required

boolean

shareVisits

boolean

showAiSummaries

boolean

avatar

One of:

object

object

id

required

string

/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

url

required

Signed URL, valid 24 h.

string

thumbUrl

string

cardUrl

string

posterUrl

string

mime

required

string

width

integer

height

integer

durationMs

integer

blurhash

string

alt

string

null

null

createdAt

required

string format: date-time

lastSeenAt

One of:

string

string format: date-time

null

null

csrfToken

Web clients only.

string

deviceToken

Device clients only. Shown once.

string

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "csrfToken": "csrf_demoWebToken0123456789abcdef",
  "member": {
    "avatar": null,
    "createdAt": "2026-09-17T09:00:00.000Z",
    "displayName": "Mali",
    "id": "mem_01j9kt0d8rwgmhnmxkmv0frnr0",
    "lastSeenAt": null,
    "locale": "en",
    "reducedMotion": false,
    "role": "owner",
    "shareVisits": true,
    "showAiSummaries": true,
    "textScale": 1,
    "theme": "system",
    "username": "mali"
  }
}

400

Invalid request.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

code

required

string

i18nKey

string

detail

string

fields

Array<object>

object

path

required

string

code

required

string

i18nKey

string

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}

409

Conflicts with current state.

Media typeapplication/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

code

required

string

i18nKey

string

detail

string

fields

Array<object>

object

path

required

string

code

required

string

i18nKey

string

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}