API overview & errors
Use your provider’s HTTPS API URL. Routes are under /v1; requests use a team bearer token, JSON field names use snake_case, and errors use {"error":"message"}.
Reference
Section titled “Reference”Endpoint reference lists every Wisps endpoint, request, response, and schema. Download the OpenAPI 3.1 document for tooling and client generation. WebSocket endpoints appear with HTTP 101 responses; their framing is described under sessions.
Errors
Section titled “Errors”| Status | Meaning | Next step |
|---|---|---|
| 400 | Invalid request or command could not start | Check fields and executable |
| 401 | Missing or invalid credential | Check your team token |
| 403 | Not permitted, quota, or incompatible token kind | Check permissions, mode, and quota |
| 404 | Missing wisp or another team’s wisp | Check name and team |
| 409 | Conflict or expired ephemeral lifetime | Check state before retrying |
| 410 | Wisp automatically deleted | Create a new wisp |
| 429 | Too many requests | Back off and retry |
| 503 | Capacity or service temporarily unavailable | Back off; check whether work already ran |
A command’s nonzero exit code is a result inside HTTP 200, not an API error. Do not blindly replay commands after a connection failure.
Compatibility
Section titled “Compatibility”Clients should ignore unfamiliar response fields. Use your provider’s API URL rather than assuming a shared hosted endpoint. Some discovery endpoints apply only to multi-host deployments; see each route’s description.
Request limits
Section titled “Request limits”Send one JSON value. The fleet rejects unknown fields and limits JSON request bodies to 64 KiB; a standalone host allows up to 1 MiB. File upload bodies use their file route’s rules.