Endpoint reference

Use your provider’s API URL and a team bearer token. Download the OpenAPI document. For working examples, start with the quickstart.

Endpoints

GET /healthz

Liveness; prints ok

Does not require a bearer token.

Status	Description	Response
200	OK	`string`

GET /readyz

Readiness: 200 when the fleet database answers, otherwise 503

Does not require a bearer token.

Fleet only.

Status	Description	Response
200	OK	`string`
503	Service Unavailable	`Error`

GET /v1/regions

Regions the team can create wisps in, with probe URLs for timing

Requires a team bearer token.

Fleet only.

Status	Description	Response
200	OK	`RegionList`
401	Unauthorized	`Error`

GET /v1/wisps

List the team’s wisps, optionally only those with given labels

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`label`	query	`string`	No	key=value; repeat to require several

Status	Description	Response
200	OK	`WispList`
400	Bad Request	`Error`
401	Unauthorized	`Error`

POST /v1/wisps

Create a wisp (name optional: one is generated); waits until it has booted unless no_start

Requires a team bearer token.

Request body (required):

application/json: CreateWispRequest

Status	Description	Response
201	Created	`Wisp`
400	Bad Request	`Error`
401	Unauthorized	`Error`
403	Forbidden	`Error`
409	Conflict	`Error`
503	Service Unavailable	`Error`

DELETE /v1/wisps/{name}

Destroy a wisp, its disk and its checkpoints

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes

Status	Description	Response
204	No Content	No body
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

GET /v1/wisps/{name}

Get one wisp; never boots it

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes

Status	Description	Response
200	OK	`Wisp`
401	Unauthorized	`Error`
404	Not Found	`Error`

PATCH /v1/wisps/{name}

Change the lifecycle mode, idle timeout or labels

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes

Request body (required):

application/json: UpdateOptions

Status	Description	Response
200	OK	`Wisp`
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

GET /v1/wisps/{name}/checkpoints

List checkpoints

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes

Status	Description	Response
200	OK	`Checkpoint[]`
401	Unauthorized	`Error`
404	Not Found	`Error`

POST /v1/wisps/{name}/checkpoints

Create a checkpoint (action create)

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`Idempotency-Key`	header	`string`	No	Same value as the body’s key; the SDK sends it and the fleet forwards it

Request body (required):

application/json: VersionRequest

Status	Description	Response
200	OK	`WispOperation`
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
503	Service Unavailable	`Error`

DELETE /v1/wisps/{name}/checkpoints/{id}

Delete a checkpoint (action delete)

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`id`	path	`string`	Yes
`Idempotency-Key`	header	`string`	No	Same value as the body’s key; the SDK sends it and the fleet forwards it

Request body (required):

application/json: VersionRequest

Status	Description	Response
200	OK	`WispOperation`
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
503	Service Unavailable	`Error`

GET /v1/wisps/{name}/checkpoints/{id}

Get one checkpoint

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`id`	path	`string`	Yes

Status	Description	Response
200	OK	`Checkpoint`
401	Unauthorized	`Error`
404	Not Found	`Error`

GET /v1/wisps/{name}/exec

Run a command over a WebSocket stream

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`cmd`	query	`string`	Yes	Command and arguments, one value each (repeat)
`env`	query	`string`	No	KEY=VALUE (repeat)
`dir`	query	`string`	No	Working directory
`tty`	query	`string`	No	1 for a terminal
`cols`	query	`string`	No	Terminal columns
`rows`	query	`string`	No	Terminal rows
`detachable`	query	`string`	No	1 to keep running after disconnect
`timeout`	query	`string`	No	Kill after this duration, e.g. 30s

Status	Description	Response
101	Switching to a WebSocket stream; see docs/api/wisps.md#streams	No body
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

DELETE /v1/wisps/{name}/fs

Remove a file or directory

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`path`	query	`string`	Yes
`recursive`	query	`string`	No	1 to remove a directory tree

Status	Description	Response
204	No Content	No body
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

GET /v1/wisps/{name}/fs

Read a file

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`path`	query	`string`	Yes	File path; relative paths start at the user’s home

Status	Description	Response
200	OK	`string`
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

PUT /v1/wisps/{name}/fs

Write a file atomically

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`path`	query	`string`	Yes
`mode`	query	`string`	No	Octal permissions, e.g. 644
`mkdirs`	query	`string`	No	1 to create parent directories

Request body (required):

application/octet-stream: string

Status	Description	Response
204	No Content	No body
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

GET /v1/wisps/{name}/fs/list

List a directory

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`path`	query	`string`	No	Directory; default the user’s home

Status	Description	Response
200	OK	`DirList`
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

POST /v1/wisps/{name}/fs/mkdir

Create a directory

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`path`	query	`string`	Yes
`parents`	query	`string`	No	1 to create parents

Status	Description	Response
204	No Content	No body
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

GET /v1/wisps/{name}/operations/{key}

State of a checkpoint operation by its key

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`key`	path	`string`	Yes

Status	Description	Response
200	OK	`WispOperation`
401	Unauthorized	`Error`
404	Not Found	`Error`

GET /v1/wisps/{name}/proxy/{port}

TCP to a port inside the wisp, as binary WebSocket messages

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`port`	path	`string`	Yes

Status	Description	Response
101	Switching to a WebSocket stream; see docs/api/wisps.md#streams	No body
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

POST /v1/wisps/{name}/restore

Restore a checkpoint (action restore, ack true); saves a safety checkpoint first

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`Idempotency-Key`	header	`string`	No	Same value as the body’s key; the SDK sends it and the fleet forwards it

Request body (required):

application/json: VersionRequest

Status	Description	Response
200	OK	`WispOperation`
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
503	Service Unavailable	`Error`

POST /v1/wisps/{name}/run

Run a command to completion: exit code, stdout and stderr in one response (server-sent events with Accept: text/event-stream)

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes

Request body (required):

application/json: RunOptions

Status	Description	Response
200	OK	`RunResult`
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

GET /v1/wisps/{name}/sessions

List sessions; never boots or wakes the wisp

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes

Status	Description	Response
200	OK	`SessionList`
401	Unauthorized	`Error`
404	Not Found	`Error`

DELETE /v1/wisps/{name}/sessions/{id}

Signal a session (default KILL)

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`id`	path	`string`	Yes
`signal`	query	`string`	No	Signal name, e.g. TERM

Status	Description	Response
204	No Content	No body
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

GET /v1/wisps/{name}/sessions/{id}/attach

Reattach to a session: scrollback, then live output

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`id`	path	`string`	Yes

Status	Description	Response
101	Switching to a WebSocket stream; see docs/api/wisps.md#streams	No body
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

DELETE /v1/wisps/{name}/sessions/{id}/hold

Release a kept session

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`id`	path	`string`	Yes

Status	Description	Response
200	OK	`Session`
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

POST /v1/wisps/{name}/sessions/{id}/hold

Keep a detached session (holds an on-demand wisp awake)

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes
`id`	path	`string`	Yes

Status	Description	Response
200	OK	`Session`
400	Bad Request	`Error`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
410	Gone	`Error`
503	Service Unavailable	`Error`

POST /v1/wisps/{name}/start

Start or wake; records intent running

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes

Status	Description	Response
200	OK	`Wisp`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
503	Service Unavailable	`Error`

POST /v1/wisps/{name}/stop

Stop; records intent stopped

Requires a team bearer token.

Parameter	Location	Type	Required	Description
`name`	path	`string`	Yes

Status	Description	Response
200	OK	`Wisp`
401	Unauthorized	`Error`
404	Not Found	`Error`
409	Conflict	`Error`
503	Service Unavailable	`Error`

Schemas

Activity

Field	Type	Required	Description
`busy`	`boolean`	Yes
`checked`	`string`	Yes	Format: date-time.
`error`	`string`	No
`idle_since`	`string`	No	Format: date-time.
`reasons`	`string[]`	No
`stops_at`	`string`	No	Format: date-time.

Checkpoint

Field	Type	Required	Description
`auto`	`boolean`	No
`capture`	`string`	No
`comment`	`string`	No
`created`	`string`	Yes	Format: date-time.
`id`	`string`	Yes
`restorable`	`boolean`	Yes

CreateWispRequest

Field	Type	Required
`delete_after_stopped_seconds`	`integer`	No
`idle_timeout_seconds`	`integer`	No
`labels`	`object`	No
`max_lifetime_seconds`	`integer`	No
`mode`	`string`	No
`name`	`string`	Yes
`near`	`string`	No
`no_start`	`boolean`	No
`region`	`string`	No
`size`	`string`	No

DirEntry

Field	Type	Required	Description
`is_dir`	`boolean`	Yes
`mod_time`	`string`	Yes	Format: date-time.
`mode`	`integer`	Yes
`name`	`string`	Yes
`size`	`integer`	Yes

DirList

Field	Type	Required	Description
`entries`	`DirEntry[]`	Yes

Error

Field	Type	Required	Description
`error`	`string`	Yes

Region

Field	Type	Required
`available`	`boolean`	Yes
`name`	`string`	Yes
`probes`	`string[]`	No

RegionList

Field	Type	Required	Description
`regions`	`Region[]`	Yes

Restart

Field	Type	Required	Description
`count`	`integer`	Yes
`failures`	`integer`	No
`last_error`	`string`	No
`last_restart`	`string`	No	Format: date-time.
`next_attempt`	`string`	No	Format: date-time.

RunOptions

Field	Type	Required
`cmd`	`string[]`	No
`dir`	`string`	No
`encoding`	`string`	No
`env`	`object`	No
`max_output_bytes`	`integer`	No
`script`	`string`	No
`stdin`	`string`	No
`timeout_seconds`	`integer`	No

RunResult

Field	Type	Required
`duration_ms`	`integer`	Yes
`encoding`	`string`	Yes
`exit_code`	`integer`	Yes
`stderr`	`string`	Yes
`stderr_truncated`	`boolean`	Yes
`stdout`	`string`	Yes
`stdout_truncated`	`boolean`	Yes
`timed_out`	`boolean`	Yes

Session

Field	Type	Required	Description
`clients`	`integer`	Yes
`cols`	`integer`	No
`command`	`string[]`	Yes
`created`	`string`	Yes	Format: date-time.
`exit_code`	`integer`	Yes
`exited`	`boolean`	Yes
`held`	`boolean`	No
`id`	`string`	Yes
`pid`	`integer`	Yes
`rows`	`integer`	No
`tty`	`boolean`	Yes

SessionList

Field	Type	Required	Description
`sessions`	`Session[]`	Yes
`status`	`string`	No

UpdateOptions

Field	Type	Required
`delete_after_stopped_seconds`	`integer`	No
`idle_timeout_seconds`	`integer`	No
`labels`	`object`	Yes
`max_lifetime_seconds`	`integer`	No
`mode`	`string`	No

VersionRequest

Field	Type	Required
`ack`	`boolean`	No
`action`	`string`	Yes
`checkpoint_id`	`string`	No
`comment`	`string`	No
`key`	`string`	Yes
`wisp_id`	`string`	Yes

Wisp

Field	Type	Required	Description
`activity`	`Activity`	No
`checkpoints`	`integer`	Yes
`created`	`string`	Yes	Format: date-time.
`delete_after_stopped_seconds`	`integer`	No
`delete_at`	`string`	No	Format: date-time.
`id`	`string`	No
`idle_timeout_seconds`	`integer`	No
`intent`	`string`	No
`intent_pending`	`boolean`	No
`labels`	`object`	No
`last_activity`	`string`	No	Format: date-time.
`lifetime_ends_at`	`string`	No	Format: date-time.
`max_lifetime_seconds`	`integer`	No
`mode`	`string`	No
`name`	`string`	Yes
`near`	`string`	No
`policy_pending`	`boolean`	No
`region`	`string`	No
`restart`	`Restart`	No
`size`	`string`	Yes
`status`	`string`	Yes
`stop_reason`	`string`	No

WispList

Field	Type	Required	Description
`wisps`	`Wisp[]`	Yes

WispOperation

Field	Type	Required
`action`	`string`	Yes
`disk_restored`	`boolean`	No
`error`	`string`	No
`id`	`string`	Yes
`safety_checkpoint_id`	`string`	No
`state`	`string`	Yes
`target`	`string`	No