Computer API

Persistent personal computers for agents. A machine is the core resource: a durable computer that can be stopped and started without losing its files.

Authentication. Every request carries either an organization API key as Authorization: Bearer sk_..., or the first-party computer_session cookie a browser gets from POST /v1/auth/login. There is no third way in.

Errors. Every non-2xx response is the same envelope: { error: { code, message, request_id, details?, quota? } }. Switch on code, which is a closed set; message is written for a person and may be reworded.

Repeating a request. Any unsafe request accepts an Idempotency-Key header, and that is what makes retrying one safe: a repeat replays the first response instead of creating a second machine. Reusing a key with a different body is a conflict.

Lists. Every list is cursor-paginated and answers { data, next_cursor, has_more }. A cursor is opaque; pass back what the last page returned and never construct one.

auth

Signup, login, logout and browser sessions. First-party: there is no hosted auth provider anywhere in this product.

• POST
  create a user and their personal organization/v1/auth/signup
• POST
  start a browser session/v1/auth/login
• POST
  revoke the current browser session/v1/auth/logout
• GET
  the authenticated principal and its active organization/v1/auth/me
• GET
  list browser sessions/v1/auth/sessions
• DELETE
  revoke a browser session/v1/auth/sessions/{auth_session_id}
• POST
  change the active organization/v1/auth/switch-organization

organizations

The unit every machine, key and bill belongs to. A user gets a personal one at signup and may belong to more.

• GET
  organizations the user belongs to/v1/organizations
• POST
  create an organization/v1/organizations
• GET
  get an organization/v1/organizations/{organization_id}

members

Membership, roles and invitations within the active organization.

• GET
  list members of the active organization/v1/members
• DELETE
  remove a member/v1/members/{membership_id}
• PATCH
  change a member's role/v1/members/{membership_id}
• GET
  list pending invitations/v1/invitations
• POST
  invite someone to the organization/v1/invitations
• DELETE
  revoke an invitation/v1/invitations/{invitation_id}
• POST
  accept an invitation/v1/invitations/accept

api-keys

Organization API keys and their scopes. The secret is returned once, at creation, and never again.

• GET
  list api keys/v1/api-keys
• POST
  create an api key, returning the secret once/v1/api-keys
• DELETE
  revoke an api key/v1/api-keys/{api_key_id}

machines

The core resource. Creating one boots a computer; stopping it keeps the disk and deleting it destroys it. Forking copies a disk into a second machine that owes the first nothing afterwards.

• GET
  list machines/v1/machines
• POST
  create a machine/v1/machines
• GET
  get a machine/v1/machines/{machine_id}
• DELETE
  delete a machine/v1/machines/{machine_id}
• PATCH
  update a machine/v1/machines/{machine_id}
• POST
  start a stopped machine/v1/machines/{machine_id}/start
• POST
  stop a machine, keeping its files/v1/machines/{machine_id}/stop
• POST
  stop and start a machine/v1/machines/{machine_id}/restart
• POST
  fork a running machine/v1/machines/{machine_id}/fork
• GET
  list a machine's events/v1/machines/{machine_id}/events

images

The server-owned catalog of base disk images a machine boots from. machines.create accepts any id listed here and uses the image marked default when a request names none. Deprecated images stay listed, with deprecated_at set, because existing machines still reference them.

• GET
  list machine images/v1/images

computer

Driving a machine the way a person would: its screen, pointer, keyboard, clipboard, terminals, files and browser. Every coordinate is in the pixel space of the machine’s current display, and one outside it is rejected rather than clamped.

• GET
  capture the machine's screen/v1/machines/{machine_id}/screenshot
• GET
  the machine's current display geometry/v1/machines/{machine_id}/display
• POST
  run a command on the machine/v1/machines/{machine_id}/exec
• GET
  read the machine's clipboard/v1/machines/{machine_id}/clipboard
• PUT
  write the machine's clipboard/v1/machines/{machine_id}/clipboard
• POST
  mint a short-lived ticket for a realtime connection/v1/machines/{machine_id}/connect
• POST
  move the pointer/v1/machines/{machine_id}/mouse/move
• POST
  click the pointer/v1/machines/{machine_id}/mouse/click
• POST
  drag the pointer/v1/machines/{machine_id}/mouse/drag
• POST
  scroll the wheel/v1/machines/{machine_id}/mouse/scroll
• POST
  type text/v1/machines/{machine_id}/keyboard/type
• POST
  press one key/v1/machines/{machine_id}/keyboard/key
• POST
  press a key combination/v1/machines/{machine_id}/keyboard/hotkey
• POST
  resize the machine's display/v1/machines/{machine_id}/display/resize
• GET
  list the machine's terminals/v1/machines/{machine_id}/terminals
• POST
  open a terminal on the machine/v1/machines/{machine_id}/terminals
• DELETE
  close a terminal/v1/machines/{machine_id}/terminals/{terminal_id}
• GET
  list a directory on the machine/v1/machines/{machine_id}/files
• GET
  read a file from the machine/v1/machines/{machine_id}/files/content
• PUT
  write a file to the machine/v1/machines/{machine_id}/files/content
• POST
  open a url in the machine's browser/v1/machines/{machine_id}/browser/open
• GET
  list the browser's open tabs/v1/machines/{machine_id}/browser/tabs

sessions

A connection to a machine, and the single input lease that hangs off it. At most one session may send input at a time, which is what makes human takeover safe rather than interleaved.

• GET
  list sessions/v1/sessions
• POST
  open a session on a machine/v1/sessions
• DELETE
  close a session/v1/sessions/{session_id}
• GET
  read the current input lease/v1/machines/{machine_id}/input-lease
• POST
  acquire or renew the input lease/v1/machines/{machine_id}/input-lease
• DELETE
  release the input lease/v1/machines/{machine_id}/input-lease

templates

Named starting states. A template is a snapshot with a name and an organization behind it, so a team can agree on what its standard box is.

• GET
  list templates/v1/templates
• POST
  create a template/v1/templates
• GET
  get a template/v1/templates/{template_id}
• DELETE
  delete a template/v1/templates/{template_id}

snapshots

Captured disks. A capture holds files, installed software and browser profile data, and holds no RAM and no live process state. Captures of one machine form a chain and only the newest can be deleted.

• GET
  list snapshots/v1/snapshots
• POST
  capture a machine's disk/v1/snapshots
• GET
  get a snapshot/v1/snapshots/{snapshot_id}
• DELETE
  delete a snapshot/v1/snapshots/{snapshot_id}
• POST
  restore a machine from a snapshot/v1/machines/{machine_id}/restore

ports

Publishing a guest port at its own https hostname. Private by default; the credential is in the response that creates it and nowhere else.

• GET
  list a machine's published ports/v1/machines/{machine_id}/ports
• POST
  publish a port on the machine at its own https url/v1/machines/{machine_id}/ports
• GET
  get a published port/v1/machines/{machine_id}/ports/{preview_id}
• DELETE
  stop publishing a port/v1/machines/{machine_id}/ports/{preview_id}
• GET
  list published ports/v1/ports

secrets

Values delivered into tmpfs inside a machine. A stored value is never returned - there is no read route here and no field one could travel in - and a snapshot, fork or template does not carry it.

• GET
  list a machine's secret names/v1/machines/{machine_id}/secrets
• PUT
  store a secret for the machine/v1/machines/{machine_id}/secrets
• DELETE
  revoke a secret/v1/machines/{machine_id}/secrets/{name}
• GET
  list secret names/v1/secrets

usage

The metered record behind a bill: raw records for a period, and the same records bucketed for charting. This is the source of truth, not the provider’s copy.

• GET
  list usage records/v1/usage
• GET
  usage totals bucketed over a window/v1/usage/series

plans

The server-owned catalog of plans, entitlements and rates. No price, allowance or weight is hardcoded in any client, so an older SDK can display a newer catalog.

• GET
  list plans/v1/plans
• GET
  get a plan/v1/plans/{plan_id}

billing

The organization’s account, checkout, customer portal and current-period summary.

• GET
  the organization's billing account/v1/billing
• POST
  start a checkout/v1/billing/checkout
• POST
  open the customer portal/v1/billing/portal
• GET
  usage summary for the current period/v1/billing/usage-summary