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 images
`rent`	Rent, reboot and stop machines
`manage`	Create and revoke tokens; save SSH keys and images
`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 live prices and availability by GPU family.

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; its tier says on_demand or spot. The balance must cover the first hour (else 402), which is charged when the machine starts running (1-hour minimum). Send max_price_per_gpu_hour to rent at no more than the price you saw (GET /v1/gpus/{node_id}/price): a higher live price rents nothing and gets 409.

Main routes

Method	Path	What it does
GET	`/v1/market/summary`	Live prices by GPU family (public)
GET	`/v1/market/history`	Prices by the hour per GPU family, as JSON or CSV with `format=csv` (public)
GET	`/v1/models/fit?model=owner/name`	The GPU memory a Hugging Face model needs and the cheapest GPUs that hold it now (public)
GET	`/v1/gpus`	Machines you can rent, cheapest first
GET	`/v1/gpus/{node_id}/price`	The live price of a machine now
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 / POST / DELETE	`/v1/volumes`	Your volumes: what they hold, what they cost, where they're mounted
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
GET	`/v1/support/cases`	Your support cases and our answers
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.