API

Authenticate with a token, then search, rent, manage and pay over plain JSON.

Basics

Base URL: $ARRAKIS_URL. Every request and response is JSON.
Authenticate with Authorization: Bearer ark_.... The token decides the account.
Errors are {"detail": "..."} with a meaningful status: 401 (token), 402 (balance or spend cap), 403 (scope), 404, 409, 422 (input), 429 (slow down), 503 (renting isn't open yet).
The full schema is /openapi.json; try calls in the interactive reference.

Tokens and scopes

Scope	Allows
`read`	Search machines, read your machines, volumes and templates
`rent`	Rent, reboot and stop machines
`manage`	Create and revoke tokens; save SSH keys and templates
`billing`	Balance, payments, auto-recharge, emergency stop

Create tokens on API & agents or with POST /v1/tokens. A token may carry spend_limit_usd, max_rental_hours and expires_at. A token can only create tokens with scopes it has, within its own caps.

No token needed

Shell

curl $ARRAKIS_URL/v1/market/summary

Returns what the GPU markets list, by GPU family, and rentals_open, which is false until Arrakis rents. Until then the prices are the markets' own, for planning.

Rent a machine

Shell

curl -X POST $ARRAKIS_URL/v1/instances \
  -H "Authorization: Bearer $ARRAKIS_TOKEN" -H "Content-Type: application/json" \
  -d '{"node_id": "<node>", "name": "eval", "ssh_public_key": "ssh-ed25519 AAAA...",
       "termination_hours": 4, "idempotency_key": "eval-2026-10-14"}'

Find a node_id with GET /v1/gpus. The first hour is charged when the rental is created (1-hour minimum); a balance short of it gets 402. Until renting opens, this answers 503 and charges nothing.

Main routes

Method	Path	What it does
GET	`/v1/market/summary`	What the markets list, by GPU family (public)
GET	`/v1/gpus`	Machines the markets list, cheapest first
POST	`/v1/instances`	Rent a machine
GET	`/v1/instances`, `/v1/instances/{id}`	Your machines
POST	`/v1/instances/{id}/terminate`	Stop and remove a machine
POST	`/v1/instances/{id}/schedule-removal`	Set when it removes itself
GET	`/v1/billing/account`	Balance, burn rate, when the money runs out
POST	`/v1/billing/checkout`	Start a card, Link or Apple Pay payment
POST	`/v1/billing/stop`	Stop everything and pause rentals
GET / POST / DELETE	`/v1/tokens`	List, create and revoke tokens
POST	`/mcp`	MCP for agents

Retries

Send the same idempotency_key when you retry a rental: you get the same machine back, never a second one.

Reading this as an agent? This page as Markdown.