API reference
Base URL https://api.spin.inductionlabs.com/v1. Hosted Spin is https://api.spin.inductionlabs.com/v1. The machine-readable spec is at openapi.json.
Authentication#
Every request carries a bearer token. The token’s prefix decides what it can do.
| Scope | Token | Where it lives |
|---|---|---|
| Account key | cnv_live_…, created in the dashboard | Host or CI |
| Signed-in session | Supabase access token from the dashboard | Browser |
| Wallet token | spin_agent_…, returned when a wallet is created | That agent’s sandbox |
curl "https://api.spin.inductionlabs.com/v1/account" -H "Authorization: Bearer $SPIN_API_KEY"
Conventions#
Account amounts are integer USD cents. Agent-side amounts are exact decimal USD strings. Lists return the latest 100 rows. Paid operations require a stable Idempotency-Key header: retry with the same key and body, and never retry an ambiguous paid operation under a new key.
Errors share one shape and a stable code. 402 insufficient funds, 403 wrong token scope, 409 conflicting retry or pending cleanup, 503 retryable dependency failure.
| Field | Type | Notes |
|---|---|---|
error | object | Fields: code (string); message (string). |
request_id | string |
Account endpoints#
Called from your host or CI with an account key, or by the dashboard with a signed-in session. They allocate and settle wallets and never expose resource credentials except the wallet token itself.
GET/v1/account#
Account credit balance in USD cents
Response · Account
| Field | Type | Notes |
|---|---|---|
available_cents | integer | |
reserved_cents | integer | |
spent_cents | integer | |
welcome_credit_cents | integer |
GET/v1/keys#
List account key metadata with spent_cents, reserved_cents, wallets and spend_cap_cents; never secrets
Response
JSON object.
POST/v1/keys#
Create an account key (Verified Supabase session or self-host operator only)
Request body
| Field | Type | Notes |
|---|---|---|
name required | string | 1–80 characters. |
spend_cap_cents | integer | null | Limit on spend plus budget reserved in open wallets created with this key; null for no cap. min 0. |
Response
JSON object.
PATCH/v1/keys/{id}#
Set or clear an API key spending cap; wallets that would exceed it are refused with 402 key_spend_cap
Request body
| Field | Type | Notes |
|---|---|---|
spend_cap_cents required | integer | null | Limit on spend plus budget reserved in open wallets created with this key; null for no cap. min 0. |
Response
JSON object.
DELETE/v1/keys/{id}#
Revoke an account API key
Response
JSON object.
GET/v1/wallets#
List latest 100 owned wallets. allowed_compute lists the kinds of machine a limited wallet may lease (null for any). Static-priced wallets report budget_cents, spent_cents and spent_usd in their prices, with the table in static_pricing; cost_cents and cost_usd are what the account pays
Response
JSON object.
POST/v1/wallets#
Reserve credit and mint sandbox credentials
Request body · WalletRequest
| Field | Type | Notes |
|---|---|---|
name required | string | 1–80 characters. |
budget_cents | integer | Required unless unlimited. 100–1000000. |
unlimited | boolean | No spend limit: starts with $1 of account credit and draws more ($5 at a time, or what an operation needs) until account credit, or the creating key's cap, runs out. Omit budget_cents. default false. |
expires_in_seconds | integer | Seconds until the wallet auto-closes (60..2592000). 0 means the wallet never expires; only closing settles it. 0–2592000. default 86400. |
static_pricing | any | Fixed prices for evaluations. true uses the installation's GPU price index (the median on-demand price of each GPU model across providers, with H100 SXM, PCIe and NVL priced apart and an H100 of unknown form factor at the SXM price); an object supplies a table. The wallet's offers, resources and budget are then shown in these prices and budget_cents is spent in them, while the account pays the providers' real cost: credit equal to budget_cents moves in at creation, more is drawn from the account when real cost runs ahead of the wallet's prices, and what is left returns at close. GPUs the table lacks are not offered; CPU-only machines count at market price unless cpu_hour_usd is set; model calls count at their real cost. Needs budget_cents; not with unlimited. default false. |
allowed_compute | "cpu" | "gpu" | "tpu"[] | Limit the machines the wallet may lease to these kinds, matched against each offer's accelerator; omit for any machine. ["tpu","cpu"] makes a TPU wallet: it is offered, and can lease, only Google TPU VMs and CPU-only machines, and a GPU lease is refused with 403. Model calls are unaffected. |
Response · Allocation
| Field | Type | Notes |
|---|---|---|
id | string | |
status | string | |
agent_token | string | Sensitive wallet credential. Never log it. |
env | object | Fields: SPIN_BROKER_URL (string (uri)); SPIN_BROKER_TOKEN (string): Same scoped credential as agent_token; inject only into its sandbox. |
GET/v1/wallets/{id}#
Read an owned wallet, including original budget and used budget after closure; cost_cents and cost_usd are the real cost the account pays
Response
JSON object.
GET/v1/resources#
List resource summaries across owned wallets, newest first; no resource credentials
Query parameters
| Name | Type | Notes |
|---|---|---|
wallet_id | string | Filter to an owned wallet, including closed wallets. 0–200 characters. |
before | string | The previous response next_cursor; pages contain up to 100 resources. Empty next_cursor means the last page. 0–200 characters. |
Response
JSON object.
GET/v1/wallets/{id}/token#
Retrieve the existing token for an owned, active wallet; closed or expired wallets return 409
Response · WalletToken
| Field | Type | Notes |
|---|---|---|
agent_token required | string | Existing scoped credential for an active, unexpired wallet. Never log it. |
POST/v1/wallets/{id}/close#
Freeze spending, clean up resources, settle, return unused credits. 202 with held_cents while a resource is still being cleaned up: unheld credit returns at once, the rest when cleanup is confirmed (retry, or the reconciler finishes it)
Response
JSON object.
GET/v1/wallets/{id}/resources#
List resources belonging to an owned wallet
Response
JSON object.
PUT/v1/billing/auto-topup#
Set auto top-up: charge the card saved at checkout when available credit falls below threshold_cents; threshold_cents null turns it off
Request body
| Field | Type | Notes |
|---|---|---|
threshold_cents required | integer | null | 0–100000. |
amount_cents | integer | 500–100000. |
Response
JSON object.
POST/v1/billing/checkout#
Create a Stripe Checkout session (browser session required); saves the card for auto top-up
Request body
| Field | Type | Notes |
|---|---|---|
amount_cents required | integer | 500–100000. |
Response
JSON object.
GET/v1/offers#
Every provider's current offers and prices, with spot flags and per-provider status (account or session). gpu is the provider's own GPU name; gpu_model is Spin's ("H100 SXM", "H100 PCIe", "H100 NVL", or "H100 (unknown form factor)" when the provider does not say)
Response
JSON object.
Agent endpoints#
Called from inside a sandbox with that wallet’s token. Spending is capped by the wallet budget and expiry; paid operations reserve their maximum price first and settle afterwards.
GET/v1/budget#
Inspect wallet spending (decimal USD strings)
Response
JSON object.
GET/v1/compute/offers#
List offers from every enabled provider; gpu_model names the GPU, including the H100 form factor (SXM, PCIe, NVL, or unknown form factor)
Response
JSON object.
GET/v1/compute/list#
List wallet-owned resources
Response
JSON object.
GET/v1/models#
List metered OpenRouter models
Response
JSON object.
POST/v1/compute/create#
Prepay a fixed-duration compute lease; no early-release refund
Request body · ComputeRequest
| Field | Type | Notes |
|---|---|---|
provider required | "modal" | "sfcompute" | "vastai" | "massedcompute" | "hyperbolic" | "runpod" | "verda" | "daytona" | "sfcompute_market" | "thundercompute" | "lambda" | "primeintellect" | "nebius" | "lyceum" | "sesterce" | "runcrate" | "gpuai" | "oblivus" | "scaleway" | "lium" | "hyperstack" | "civo" | "gcp" | |
spec required | object | Provider-specific spec; GET /v1/compute/offers first. Modal: gpu (e.g. H100 SXM, as offers list it),gpus,cpus,memory_gib,max_seconds; gpus 0 for a CPU sandbox; a GPU sandbox gets at most 2 cores and 16 GiB per GPU. SF: chip,max_seconds,max_queue_seconds (0-540, default 300): with no free slot the create returns status queued at once, nothing is charged while queued, and the same request ID or POST /v1/compute/status promotes it when SF places the node; the lease clock then starts at placement. Vast: offer_id,disk_gb,max_seconds (up to 86400); stop destroys the rental and disk. sfcompute_market (SF Compute 8-GPU nodes; distinct from sfcompute, which is SF Compute Autoresearch): offer_id (accelerator, e.g. h100),max_seconds; buys the whole window up front, no extension. thundercompute: offer_id (e.g. h100_x8),max_seconds, optional cpus,disk_gb. lambda: offer_id (instance type, e.g. gpu_8x_h100_sxm5),max_seconds, optional region. primeintellect: offer_id (e.g. H100_80GB_x8_SXM5@lambdalabs:us-east-1),max_seconds, optional disk_gb. nebius: offer_id (platform:preset@region, e.g. gpu-h100-sxm:8gpu-128vcpu-1600gb@eu-north1),max_seconds, optional disk_gb (64-4096). lyceum: offer_id (profile and GPU count, e.g. h100.8x),max_seconds. sesterce: offer_id (instance@cloud:region, e.g. L40S@AZ_13:desmoines-usa-1),max_seconds. runcrate: offer_id (instance type id from offers),max_seconds; billed by the started hour. gpuai: offer_id (gpu.ai offering_id from offers),max_seconds; launches pin the offering and refuse any higher price. scaleway: offer_id (type@zone, e.g. L4-1-24G@pl-waw-2),max_seconds; EUR prices converted to USD at the ECB rate plus a margin. oblivus: offer_id (flavor@location, e.g. RTX_A6000_x1@MON1),max_seconds. lium: offer_id (node executor id from offers),max_seconds, optional gpus (up to the free GPUs on the node). hyperstack: offer_id (flavor@region, e.g. n3-L40x1@CANADA-1),max_seconds. civo: offer_id (size@region, e.g. g4g.40.small@lon1),max_seconds; billed by the started hour. gcp (Google Cloud TPU VMs; offers list gpu as e.g. TPU v5e with gpus counting TPU chips, and accelerator tpu): offer_id (accelerator type@zone, e.g. v5litepod-4@us-central1-a),max_seconds; TPUs run JAX or PyTorch/XLA, not CUDA. |
Response · ComputeResource
| Field | Type | Notes |
|---|---|---|
id | string | Spin resource ID for subsequent requests. |
provider_id | string | null | |
provider | string | |
status | string | Provider state once running. New leases start as "checking": the hold is kept while Spin confirms the machine answers commands and its GPUs work; poll /v1/compute/status (each poll runs one check). A machine that has not passed within 20 minutes (or by the lease or wallet deadline) or that its provider reports dead is destroyed and shows "rejected" with a reason; its credits are released. SF leases waiting for a slot show "queued". |
billing_state | "reserved" | "uncertain" | "settled" | Payment state; settled resources may still be running and need cleanup. |
billing_policy | "prepaid_time" | |
charged_usd | string | Cumulative prepaid charge, including confirmed extensions. "0" while checking or queued, and "0" for good if the initial health check fails (the hold is released); captured in full when it passes, after which early release does not refund it. |
reserved_usd | string | Creation hold while queued, checking or unresolved; zero after capture or release. Check /v1/budget for pending extension holds. |
health_check | object | Present on gated leases: state (pending, passed, failed), deadline_at, gpus the probe expects, and checked_at or reason. |
released_usd | string | On a rejected lease: the hold returned to the wallet. |
reason | string | On a rejected lease: why Spin or the provider ended it before it became usable. |
expires_at | string (date-time) | Current deadline, ISO 8601 UTC. |
purchased_seconds | integer | |
price_hourly_usd | string | |
supports_extension | boolean | |
pricing | "static" | Present in static-priced wallets: price_hourly_usd, charged_usd and reserved_usd are in the wallet's prices. |
priced_as | object | The GPU model a static price is for, e.g. {"gpu": "H100 SXM", "gpus": 8}. |
POST/v1/compute/extend#
Prepay additional seconds on an active lease whose offer has supports_extension (SF Compute, Massed Compute and most VM providers); Modal returns extension_not_supported
Request body
| Field | Type | Notes |
|---|---|---|
id required | string | |
additional_seconds required | integer | Added to the current expiry; constrained by wallet expiry, remaining credit, and provider limits. 1–86400. |
Response · ComputeResource
| Field | Type | Notes |
|---|---|---|
id | string | Spin resource ID for subsequent requests. |
provider_id | string | null | |
provider | string | |
status | string | Provider state once running. New leases start as "checking": the hold is kept while Spin confirms the machine answers commands and its GPUs work; poll /v1/compute/status (each poll runs one check). A machine that has not passed within 20 minutes (or by the lease or wallet deadline) or that its provider reports dead is destroyed and shows "rejected" with a reason; its credits are released. SF leases waiting for a slot show "queued". |
billing_state | "reserved" | "uncertain" | "settled" | Payment state; settled resources may still be running and need cleanup. |
billing_policy | "prepaid_time" | |
charged_usd | string | Cumulative prepaid charge, including confirmed extensions. "0" while checking or queued, and "0" for good if the initial health check fails (the hold is released); captured in full when it passes, after which early release does not refund it. |
reserved_usd | string | Creation hold while queued, checking or unresolved; zero after capture or release. Check /v1/budget for pending extension holds. |
health_check | object | Present on gated leases: state (pending, passed, failed), deadline_at, gpus the probe expects, and checked_at or reason. |
released_usd | string | On a rejected lease: the hold returned to the wallet. |
reason | string | On a rejected lease: why Spin or the provider ended it before it became usable. |
expires_at | string (date-time) | Current deadline, ISO 8601 UTC. |
purchased_seconds | integer | |
price_hourly_usd | string | |
supports_extension | boolean | |
pricing | "static" | Present in static-priced wallets: price_hourly_usd, charged_usd and reserved_usd are in the wallet's prices. |
priced_as | object | The GPU model a static price is for, e.g. {"gpu": "H100 SXM", "gpus": 8}. |
POST/v1/run/close#
Freeze wallet spending and clean up agent resources
Response
JSON object.
POST/v1/compute/stop#
Stop an owned resource
Request body · ResourceID
| Field | Type | Notes |
|---|---|---|
id required | string |
Response
JSON object.
POST/v1/compute/ssh#
Ssh an owned resource
Request body · ResourceID
| Field | Type | Notes |
|---|---|---|
id required | string |
Response
JSON object.
POST/v1/compute/status#
Status an owned resource
Request body · ResourceID
| Field | Type | Notes |
|---|---|---|
id required | string |
Response
JSON object.
POST/v1/compute/exec#
Execute inside an owned remote sandbox
Request body
| Field | Type | Notes |
|---|---|---|
id required | string | |
command required | string | |
timeout | integer | 1–3600. default 300. |
Response
JSON object.
POST/v1/compute/upload#
Upload at most 512 KiB to an owned resource; use spin s5cmd for larger files
Request body
| Field | Type | Notes |
|---|---|---|
id required | string | |
path required | string | |
content_base64 required | string |
Response
JSON object.
POST/v1/compute/download#
Download a sandbox file of up to 512 KiB through the worker (works with networking off); returns content_base64, size_bytes, sha256; use spin s5cmd for larger files
Request body
| Field | Type | Notes |
|---|---|---|
id required | string | |
path required | string | Absolute path in the sandbox. |
Response
JSON object.
POST/v1/transfer/credentials#
Issue temporary S3 credentials for direct transfers within a wallet folder
Authenticate with the wallet agent token. Send {} for its full storage prefix, or {"prefix":"results","permission":"read-only","expires_seconds":28800} for a narrower session. Use endpoint_url plus access_key_id, secret_access_key and session_token in an S3 client. spin s5cmd fetches a fresh session automatically; spin transfer credentials --out session.json exports one for a GPU VM. R2 enforces the signed wallet prefix. Sessions can read/list or read/write/list/delete objects, including multipart transfers, according to permission. No bucket administration is granted. Download results before closing the wallet: closure deletes its objects and incomplete multipart uploads. Existing credentials remain valid until expiry; Spin automatically cleans up late uploads. On hosted Spin, files expire after two days; deletion is asynchronous. Returns 501 if storage is unconfigured; inactive wallets cannot mint sessions. Replaces /v1/transfer/sign.
Request body · TransferRequest
| Field | Type | Notes |
|---|---|---|
prefix | string | Relative folder inside the authenticated wallet; empty means its entire storage prefix. Absolute paths, traversal and wildcards are rejected. default "". |
permission | "read-only" | "read-write" | default "read-write". |
expires_seconds | integer | Session lifetime: 8 hours by default and maximum, capped by wallet expiry. 1–28800. default 28800. |
Response · TransferCredentials
| Field | Type | Notes |
|---|---|---|
endpoint_url required | string (uri) | R2 S3 API endpoint; file bytes travel directly here. |
region required | "auto" | |
bucket required | string | |
prefix required | string | Full permitted object prefix, including the wallet ID and trailing slash. |
s3_uri required | string | s3://bucket/prefix/ for native S3 clients. spin s5cmd maps s3://spin/ to this value. |
permission required | "read-only" | "read-write" | |
expires_at required | string (date-time) | |
expires_seconds required | integer | 1–28800. |
access_key_id required | string | Temporary session access key ID. Use all three credential fields together. |
secret_access_key required | string | Sensitive temporary secret; never log it. The parent secret is never returned. |
session_token required | string | Sensitive R2 session token; required on every S3 request. Never log it. |
POST/v1/openrouter/key#
Get wallet-scoped key and OpenAI-compatible base_url
Request body
Free-form JSON object.
Response
JSON object.
POST/v1/chat/completions#
Metered OpenRouter chat completion, billed at usage.cost; stream true relays server-sent events. Use a new Idempotency-Key per call: a streamed call cannot be replayed
Request body
| Field | Type | Notes |
|---|---|---|
model required | string | |
messages required | object[] | |
max_tokens | integer | min 1. |
stream | boolean | Relay server-sent events as they arrive; the final usage chunk carries the billed cost. default false. |
provider | object | OpenRouter provider routing. Without it the call is capped at the model's listed price, which usually only its cheapest endpoints meet. With it the cap is the dearest endpoint the selection allows, and the call holds the worst case of every endpoint under that cap. Spin always adds require_parameters true and its max_price cap. Fields: only (string[]): Provider slugs or endpoint tags, e.g. deepinfra or deepinfra/fp8 (GET /v1/models/{model}/endpoints); order (string[]); ignore (string[]); quantizations ("int4" | "int8" | "fp4" | "fp6" | "fp8" | "fp16" | "bf16" | "fp32" | "unknown"[]); sort ("price" | "throughput" | "latency"); allow_fallbacks (boolean); max_price (object). |
Response
JSON object.
GET/v1/models/{model}/endpoints#
A catalog model's OpenRouter endpoints (provider, quantization, per-token pricing, context, recent throughput and uptime) with each endpoint's slug for provider routing and within_default_cap: whether a call without a provider object can reach it
Response
JSON object.