Record a setup step

POST

/setup/step

curl --request POST \
  --url http://127.0.0.1:7700/api/setup/step \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": "network", "data": { "wired": true } }'

• On the box itself (the default listen address)
• From another device, with a paired device token, when BOX_LISTEN allows it

Owner only. Marks a step as taken. suggested in GET /setup lists the usual ids; the box accepts any id. data is at most 4 KB and holds answers, never keys; keys go to PUT /vault/{name}. The log records the step id only.

Authorizations

• deviceToken
• accessToken

Request Body^required

Media typeapplication/json

object

id

required

string

/^[a-z][\w-]{0,31}$/

data

Answers for this step. At most 4 KB as JSON.

Example

{
  "id": "network",
  "data": {
    "wired": true
  }
}

Responses

200

The setup state.

Media typeapplication/json

object

model

Whether tasks can run: the vault holds a model key. via is factory with FACTORY_API_KEY, anthropic with only ANTHROPIC_API_KEY, or null with neither.

object

ready

boolean

via

string | null

Allowed values: factory anthropic

droid

Where the Droid download stands. A task that needs Droid waits, queued, until ready.

object

state

required

string

Allowed values: ready downloading offline retrying missing

message

required

string

at

string

modelKey

False until the vault holds a model key. Without one no Droid task can start.

boolean

done

required

boolean

finishedAt

string | null format: date-time

migrated

The box already ran tasks when setup arrived

boolean

steps

required

object

key

additional properties

object

at

string format: date-time

data

suggested

required

The usual step ids, in order. Server’s screen skips folders, and Personal’s skips network, name and updates. The box accepts any id.

Array<string>

channel

The setup port for setting up from another computer.

object

open

required

boolean

until

When the port closes by itself.

string format: date-time

port

integer

urls

The addresses another computer can use.

Array<string>

remote

The box’s remote access address

string

devices

Array<object>

object

name

string

since

string format: date-time

Example

{
  "model": {
    "via": "factory"
  },
  "droid": {
    "state": "ready"
  },
  "suggested": [
    "welcome",
    "network",
    "name",
    "phone",
    "models",
    "folders",
    "safety",
    "updates"
  ]
}

400

A bad step id, or data over 4 KB.

Media typeapplication/json

object

error

required

What went wrong

string

Example ^generated

{
  "error": "example"
}

403

The owner’s route, called by someone who is not the box’s own screen or a device paired as the owner.

Media typeapplication/json

object

error

required

What went wrong

string

Example

{
  "error": "only this computer's own screen or the owner's paired device can do this"
}