Raster 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 an organization API key as Authorization: Bearer sk_.... Create one in the dashboard; the secret is shown once.

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.

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
  Restart a machine/v1/machines/{machine_id}/restart
• POST
  Fork a machine/v1/machines/{machine_id}/fork
• GET
  List a machine's events/v1/machines/{machine_id}/events
• GET
  List what has been done to a machine/v1/machines/{machine_id}/activity

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 control

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
  Take a screenshot/v1/machines/{machine_id}/screenshot
• GET
  Get the display geometry/v1/machines/{machine_id}/display
• POST
  Run a command/v1/machines/{machine_id}/exec
• GET
  Read the clipboard/v1/machines/{machine_id}/clipboard
• PUT
  Write the clipboard/v1/machines/{machine_id}/clipboard
• POST
  Create a realtime connection ticket/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 a key/v1/machines/{machine_id}/keyboard/key
• POST
  Press a key combination/v1/machines/{machine_id}/keyboard/hotkey
• POST
  Resize the display/v1/machines/{machine_id}/display/resize
• POST
  Restart the desktop session/v1/machines/{machine_id}/desktop/restart
• GET
  List terminals/v1/machines/{machine_id}/terminals
• POST
  Open a terminal/v1/machines/{machine_id}/terminals
• DELETE
  Close a terminal/v1/machines/{machine_id}/terminals/{terminal_id}
• GET
  List a directory/v1/machines/{machine_id}/files
• GET
  Read a file/v1/machines/{machine_id}/files/content
• PUT
  Write a file/v1/machines/{machine_id}/files/content
• POST
  Open a URL in the browser/v1/machines/{machine_id}/browser/open
• GET
  List open browser tabs/v1/machines/{machine_id}/browser/tabs

Sessions and input

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/v1/sessions
• DELETE
  Close a session/v1/sessions/{session_id}
• GET
  Get 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

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 snapshot/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

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}

Published 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 at its own HTTPS URL/v1/machines/{machine_id}/ports
• GET
  Get a published port/v1/machines/{machine_id}/ports/{preview_id}
• DELETE
  Unpublish a port/v1/machines/{machine_id}/ports/{preview_id}
• GET
  List all 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 on a machine/v1/machines/{machine_id}/secrets
• DELETE
  Revoke a secret/v1/machines/{machine_id}/secrets/{name}
• GET
  List all 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
  Get usage totals 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}