API reference

Auto-generated from docs/openapi.snapshot.json. Each endpoint has a dedicated page with parameters, request body, response shapes, and code samples in TypeScript, Python, and curl.

account_ssh_keys

• GET /v1/me/ssh-keys
• POST /v1/me/ssh-keys
• DELETE /v1/me/ssh-keys/{id}

admin_agent_conversations

• GET /v1/admin/agent-conversations

admin_matrix

• GET /v1/admin/matrix
• PATCH /v1/admin/plans/{slug}/features/{key}
• DELETE /v1/admin/plans/{slug}/features/{key}

admin_org_detail

• GET /v1/admin/orgs/{id}
• GET /v1/admin/orgs/{id}/audit
• GET /v1/admin/orgs/{id}/billing
• GET /v1/admin/orgs/{id}/credits-ledger
• GET /v1/admin/orgs/{id}/instances
• GET /v1/admin/orgs/{id}/plan-history
• GET /v1/admin/orgs/{id}/usage

admin_orgs

• GET /v1/admin/orgs

admin_overview

• GET /v1/admin/overview

admin_parallel_runs

• GET /v1/admin/parallel-runs

admin_seeds

• GET /v1/admin/seeds

admin_simulations

• POST /v1/admin/simulations/cache-dry-run
• POST /v1/admin/simulations/fake-clock
• POST /v1/admin/simulations/replay-user

admin_stripe

• GET /v1/admin/stripe/events
• GET /v1/admin/stripe/products
• GET /v1/admin/stripe/summary

admin_system

• GET /v1/admin/system
• PUT /v1/admin/system/flags/{key}

agent

• GET /v1/agent/conversations
• POST /v1/agent/conversations
• GET /v1/agent/conversations/{id}
• GET /v1/agent/conversations/{id}/messages
• POST /v1/agent/conversations/{id}/messages
• GET /v1/agent/conversations/{id}/stream

api_keys

• GET /v1/api-keys
• POST /v1/api-keys
• DELETE /v1/api-keys/{id}
• POST /v1/api-keys/{id}/rotate

audit

• GET /v1/admin/audit-events
• GET /v1/audit

auth

• POST /v1/auth/forgot-password
• POST /v1/auth/login
• GET /v1/auth/login/magic-link/consume — GET /v1/auth/login/magic-link/consume?token=… — consume a magic link and finish signing in.
• POST /v1/auth/login/magic-link/request — POST /v1/auth/login/magic-link/request — request a sign-in email.
• POST /v1/auth/login/mfa
• POST /v1/auth/login/mfa/send-code
• GET /v1/auth/login/mfa/state — GET /v1/auth/login/mfa/state?challenge_token=… — read the factor list and expiry for a pending login challenge.
• POST /v1/auth/login/mfa/webauthn/begin — POST /v1/auth/login/mfa/webauthn/begin — challenge-token authenticated. Returns the RequestChallengeResponse for navigator.credentials.get.
• POST /v1/auth/login/mfa/webauthn/finish — POST /v1/auth/login/mfa/webauthn/finish — complete the authentication ceremony. Sets session cookies on success (mirrors verify_login for the code-based factors).
• POST /v1/auth/logout
• GET /v1/auth/me
• PATCH /v1/auth/me
• DELETE /v1/auth/me — Soft-delete the calling user's account. See account_deletion module docs for the full cascade. Always returns 204 No Content on success and clears both auth cookies on the response — the next request from the (now-deleted) browser will be unauthenticated.
• POST /v1/auth/me/email — POST /v1/auth/me/email — request email change. Sudo-gated. The response is a constant message regardless of conflict outcome (we silently no-op when the new address is already in use, so this endpoint cannot enumerate accounts).
• POST /v1/auth/me/email/confirm — POST /v1/auth/me/email/confirm — consume the emailed confirmation token. The link is the proof; no sudo required (the user proved control of the new address by clicking the link). On success, all sessions are revoked — the user re-signs-in with the new email.
• POST /v1/auth/me/export — Returns every record the platform stores about the calling user as a single JSON document. See data_export module docs for scope, caps, and sensitive-field redaction rationale.
• POST /v1/auth/me/password
• POST /v1/auth/me/phone — POST /v1/auth/me/phone — change phone in one shot: the body carries the new phone AND the 6-digit OTP the user just received at that number via POST /v1/auth/phone/send-code. Sudo-gated.
• GET /v1/auth/me/sessions — GET /v1/auth/sessions — list this user's active sessions.
• DELETE /v1/auth/me/sessions/{id} — DELETE /v1/auth/sessions/:id — revoke a single session.
• POST /v1/auth/me/sessions/revoke-others — POST /v1/auth/me/sessions/revoke-others — sign out every device except the one making this request. The current session is identified by hashing the caller's access cookie; if the caller is using an API key (no access cookie), the keep set is empty and ALL the user's sessions are revoked. Returns the count of revoked sessions.
• POST /v1/auth/mfa/backup-codes/regenerate
• POST /v1/auth/mfa/email/enroll
• POST /v1/auth/mfa/email/verify
• GET /v1/auth/mfa/factors
• POST /v1/auth/mfa/factors/{id}/remove
• POST /v1/auth/mfa/sms/enroll
• POST /v1/auth/mfa/sms/verify
• POST /v1/auth/mfa/totp/enroll/begin
• POST /v1/auth/mfa/totp/enroll/finish
• POST /v1/auth/mfa/webauthn/register/begin — POST /v1/auth/mfa/webauthn/register/begin — start a passkey registration ceremony. Auth-required (the user is already signed in; passkeys are a step-up factor enrollment).
• POST /v1/auth/mfa/webauthn/register/finish — POST /v1/auth/mfa/webauthn/register/finish — complete the registration ceremony. The new passkey is persisted as a confirmed mfa_factors row.
• GET /v1/auth/oauth/{provider}
• GET /v1/auth/oauth/{provider}/callback
• GET /v1/auth/oauth/providers
• POST /v1/auth/phone/send-code
• POST /v1/auth/phone/verify
• POST /v1/auth/recovery/complete — POST /v1/auth/recovery/complete — consume a recovery token after the cooldown elapses. Removes ALL MFA factors and revokes every session. The user re-signs-in fresh and re-enrolls factors.
• POST /v1/auth/recovery/request — POST /v1/auth/recovery/request — request a recovery email. Always 200 with a constant message. The 24h cooldown means even a successful request can't bypass MFA in real time.
• POST /v1/auth/refresh
• POST /v1/auth/reset-password
• POST /v1/auth/set-password
• POST /v1/auth/signup
• POST /v1/auth/sudo — POST /v1/auth/sudo — re-verify the user's password and mint a 5-minute sudo-grant cookie. Subsequent calls to destructive routes (account deletion, MFA factor removal, billing-email change, API-key rotation) succeed only when the request also carries the sudo cookie. The cookie is HttpOnly + Secure + SameSite=Strict (NOT Lax — sudo never rides on cross-origin nav) and path-scoped to /v1.
• GET /v1/auth/verify-email

base_images

• GET /v1/base-images
• GET /v1/base-images/{id}
• DELETE /v1/base-images/{id}
• GET /v1/base-images/default
• GET /v1/base-images/family/{family}
• POST /v1/base-images/family/{family}/rollback
• GET /v1/base-images/family/{family}/versions
• POST /v1/images/abort
• POST /v1/images/prepare
• POST /v1/images/promote

billing

• POST /v1/admin/plans/{slug}/sync-stripe
• GET /v1/billing
• GET /v1/billing/auto-recharge
• PUT /v1/billing/auto-recharge
• POST /v1/billing/cancel
• POST /v1/billing/checkout
• POST /v1/billing/confirm-from-token
• GET /v1/billing/credits/balance
• GET /v1/billing/credits/ledger
• POST /v1/billing/customer-sessions
• GET /v1/billing/invoices
• GET /v1/billing/payment-methods
• DELETE /v1/billing/payment-methods/{id}
• POST /v1/billing/payment-methods/{id}/default
• POST /v1/billing/portal
• POST /v1/billing/setup-intents
• POST /v1/billing/topup
• GET /v1/billing/upcoming

checkpoints

• GET /v1/instances/{id}/checkpoints
• POST /v1/instances/{id}/checkpoints
• POST /v1/instances/{id}/rollback
• GET /v1/instances/{instance_id}/checkpoints/{checkpoint_id}
• DELETE /v1/instances/{instance_id}/checkpoints/{checkpoint_id}

compute_servers

• GET /v1/admin/servers
• GET /v1/admin/servers/{id}
• POST /v1/admin/servers/{id}/drain
• GET /v1/admin/servers/{id}/metrics
• PATCH /v1/admin/servers/{id}/status
• GET /v1/admin/servers/{id}/vm-storage

credit_grants

• GET /v1/admin/credits-grants/{id}
• POST /v1/admin/credits-grants/{id}/revoke
• GET /v1/admin/orgs/{org_id}/credits/grants
• POST /v1/admin/orgs/{org_id}/credits/grants

entitlements

• GET /v1/orgs/me/entitlements

events

• GET /v1/admin/activity/stream

exec

• GET /v1/instances/{id}/exec
• POST /v1/instances/{id}/exec
• POST /v1/instances/{id}/exec/stream — SSE stream of exec frames. See service::stream for frame shapes.

files

• GET /v1/instances/{id}/files
• POST /v1/instances/{id}/files
• POST /v1/instances/{id}/files/edit
• GET /v1/instances/{id}/files/list

haywire

• POST /v1/haywire/plan/preview
• POST /v1/haywire/runs

health

• GET /health
• GET /health/live — Cheapest possible probe — process is up.
• GET /health/ready
• GET /health/startup

instances

• GET /v1/instances
• POST /v1/instances
• GET /v1/instances/{id}
• PATCH /v1/instances/{id}
• DELETE /v1/instances/{id}
• POST /v1/instances/{id}/fork

internal

• GET /v1/internal/base-images/{id}/chunks
• GET /v1/internal/base-images/chunks

invitations

• GET /v1/auth/invitations/{token}
• POST /v1/auth/invitations/{token}/accept
• GET /v1/orgs/{org_id}/invitations
• POST /v1/orgs/{org_id}/invitations
• DELETE /v1/orgs/{org_id}/invitations/{inv_id}

lsp

• POST /v1/instances/{id}/lsp/request

members

• GET /v1/orgs/{org_id}/members
• PATCH /v1/orgs/{org_id}/members/{user_id}
• DELETE /v1/orgs/{org_id}/members/{user_id}

notifications

• GET /v1/notifications
• POST /v1/notifications/{id}/read
• POST /v1/notifications/read-all
• GET /v1/notifications/settings
• PUT /v1/notifications/settings

orgs

• GET /v1/orgs
• GET /v1/orgs/{id}
• GET /v1/orgs/{id}/members
• GET /v1/orgs/me/ip-allowlist
• POST /v1/orgs/me/ip-allowlist
• DELETE /v1/orgs/me/ip-allowlist/{entry_id}

parallel

• GET /v1/parallel/runs
• POST /v1/parallel/runs
• GET /v1/parallel/runs/{id}
• POST /v1/parallel/runs/{id}/cancel
• GET /v1/parallel/runs/{id}/members
• GET /v1/parallel/runs/{id}/results
• GET /v1/parallel/runs/{id}/stream

port_forwards

• GET /v1/instances/{id}/port-forwards
• POST /v1/instances/{id}/port-forwards
• DELETE /v1/instances/{instance_id}/port-forwards/{forward_id}

probes

• GET /v1/admin/probes/catalog
• GET /v1/admin/probes/grid
• GET /v1/admin/probes/runs
• POST /v1/internal/probes/api-key/issue — Mint (or rotate) the probe-runner's API key.
• GET /v1/probes

profiles

• GET /v1/profiles
• POST /v1/profiles
• GET /v1/profiles/{id}
• PATCH /v1/profiles/{id}
• DELETE /v1/profiles/{id}

sessions

• GET /v1/instances/{id}/sessions
• DELETE /v1/instances/{instance_id}/sessions/{session_id}

snapshots

• GET /v1/instances/{id}/snapshots
• POST /v1/instances/{id}/snapshots
• GET /v1/instances/{id}/snapshots/{snapshot_id}
• DELETE /v1/instances/{id}/snapshots/{snapshot_id}
• POST /v1/instances/{id}/snapshots/{snapshot_id}/restore

ssh

• GET /v1/instances/{id}/ssh
• GET /v1/instances/{id}/ssh-keys
• PUT /v1/instances/{id}/ssh-keys

usage

• POST /v1/admin/usage/aggregate
• GET /v1/admin/usage/aggregates
• GET /v1/admin/usage/events

users

• GET /v1/admin/users

vm_admin

• GET /v1/admin/instances
• GET /v1/admin/vms
• POST /v1/admin/vms/{id}/force-stop
• GET /v1/admin/vms/{id}/storage-metrics

vms

• GET /v1/instances/{id}/vm
• POST /v1/instances/{id}/vm
• DELETE /v1/instances/{id}/vm
• POST /v1/instances/{id}/vm/flush
• POST /v1/instances/{id}/vm/restart

webhooks

• GET /v1/admin/webhooks/dlq
• POST /v1/admin/webhooks/dlq/{id}/retry
• POST /v1/admin/webhooks/dlq/reap
• POST /v1/admin/webhooks/process-queue
• GET /v1/webhooks
• POST /v1/webhooks
• GET /v1/webhooks/{id}
• PATCH /v1/webhooks/{id}
• DELETE /v1/webhooks/{id}
• GET /v1/webhooks/{id}/deliveries
• POST /v1/webhooks/{id}/test