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.

ScopeTokenWhere it lives
Account keycnv_live_…, created in the dashboardHost or CI
Signed-in sessionSupabase access token from the dashboardBrowser
Wallet tokenspin_agent_…, returned when a wallet is createdThat 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.

FieldTypeNotes
errorobjectFields: code (string); message (string).
request_idstring

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

Auth: Account key · Returns 200

Response · Account

FieldTypeNotes
available_centsinteger
reserved_centsinteger
spent_centsinteger
welcome_credit_centsinteger

GET/v1/keys#

List account key metadata with spent_cents, reserved_cents, wallets and spend_cap_cents; never secrets

Auth: Account key · Returns 200

Response

JSON object.

POST/v1/keys#

Create an account key (Verified Supabase session or self-host operator only)

Auth: Signed-in session · Returns 201

Request body

FieldTypeNotes
name requiredstring1–80 characters.
spend_cap_centsinteger | nullLimit 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

Auth: Signed-in session · id in the path · Returns 200

Request body

FieldTypeNotes
spend_cap_cents requiredinteger | nullLimit 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

Auth: Signed-in session · id in the path · Returns 200

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

Auth: Account key · Returns 200

Response

JSON object.

POST/v1/wallets#

Reserve credit and mint sandbox credentials

Auth: Account key · Idempotency-Key header required · Returns 201

Request body · WalletRequest

FieldTypeNotes
name requiredstring1–80 characters.
budget_centsintegerRequired unless unlimited. 100–1000000.
unlimitedbooleanNo 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_secondsintegerSeconds until the wallet auto-closes (60..2592000). 0 means the wallet never expires; only closing settles it. 0–2592000. default 86400.
static_pricinganyFixed 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

FieldTypeNotes
idstring
statusstring
agent_tokenstringSensitive wallet credential. Never log it.
envobjectFields: 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

Auth: Account key · id in the path · Returns 200

Response

JSON object.

GET/v1/resources#

List resource summaries across owned wallets, newest first; no resource credentials

Auth: Account key · Returns 200

Query parameters

NameTypeNotes
wallet_idstringFilter to an owned wallet, including closed wallets. 0–200 characters.
beforestringThe 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

Auth: Account key · id in the path · Returns 200

Response · WalletToken

FieldTypeNotes
agent_token requiredstringExisting 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)

Auth: Account key · id in the path · Returns 200

Response

JSON object.

GET/v1/wallets/{id}/resources#

List resources belonging to an owned wallet

Auth: Account key · id in the path · Returns 200

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

Auth: Signed-in session · Returns 200

Request body

FieldTypeNotes
threshold_cents requiredinteger | null0–100000.
amount_centsinteger500–100000.

Response

JSON object.

POST/v1/billing/checkout#

Create a Stripe Checkout session (browser session required); saves the card for auto top-up

Auth: Signed-in session · Idempotency-Key header required · Returns 200

Request body

FieldTypeNotes
amount_cents requiredinteger500–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)

Auth: Account key · Returns 200

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)

Auth: Wallet token · Returns 200

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)

Auth: Wallet token · Returns 200

Response

JSON object.

GET/v1/compute/list#

List wallet-owned resources

Auth: Wallet token · Returns 200

Response

JSON object.

GET/v1/models#

List metered OpenRouter models

Auth: Wallet token · Returns 200

Response

JSON object.

POST/v1/compute/create#

Prepay a fixed-duration compute lease; no early-release refund

Auth: Wallet token · Idempotency-Key header required · Returns 200

Request body · ComputeRequest

FieldTypeNotes
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 requiredobjectProvider-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

FieldTypeNotes
idstringSpin resource ID for subsequent requests.
provider_idstring | null
providerstring
statusstringProvider 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_usdstringCumulative 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_usdstringCreation hold while queued, checking or unresolved; zero after capture or release. Check /v1/budget for pending extension holds.
health_checkobjectPresent on gated leases: state (pending, passed, failed), deadline_at, gpus the probe expects, and checked_at or reason.
released_usdstringOn a rejected lease: the hold returned to the wallet.
reasonstringOn a rejected lease: why Spin or the provider ended it before it became usable.
expires_atstring (date-time)Current deadline, ISO 8601 UTC.
purchased_secondsinteger
price_hourly_usdstring
supports_extensionboolean
pricing"static"Present in static-priced wallets: price_hourly_usd, charged_usd and reserved_usd are in the wallet's prices.
priced_asobjectThe 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

Auth: Wallet token · Idempotency-Key header required · Returns 200

Request body

FieldTypeNotes
id requiredstring
additional_seconds requiredintegerAdded to the current expiry; constrained by wallet expiry, remaining credit, and provider limits. 1–86400.

Response · ComputeResource

FieldTypeNotes
idstringSpin resource ID for subsequent requests.
provider_idstring | null
providerstring
statusstringProvider 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_usdstringCumulative 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_usdstringCreation hold while queued, checking or unresolved; zero after capture or release. Check /v1/budget for pending extension holds.
health_checkobjectPresent on gated leases: state (pending, passed, failed), deadline_at, gpus the probe expects, and checked_at or reason.
released_usdstringOn a rejected lease: the hold returned to the wallet.
reasonstringOn a rejected lease: why Spin or the provider ended it before it became usable.
expires_atstring (date-time)Current deadline, ISO 8601 UTC.
purchased_secondsinteger
price_hourly_usdstring
supports_extensionboolean
pricing"static"Present in static-priced wallets: price_hourly_usd, charged_usd and reserved_usd are in the wallet's prices.
priced_asobjectThe 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

Auth: Wallet token · Returns 200

Response

JSON object.

POST/v1/compute/stop#

Stop an owned resource

Auth: Wallet token · Returns 200

Request body · ResourceID

FieldTypeNotes
id requiredstring

Response

JSON object.

POST/v1/compute/ssh#

Ssh an owned resource

Auth: Wallet token · Returns 200

Request body · ResourceID

FieldTypeNotes
id requiredstring

Response

JSON object.

POST/v1/compute/status#

Status an owned resource

Auth: Wallet token · Returns 200

Request body · ResourceID

FieldTypeNotes
id requiredstring

Response

JSON object.

POST/v1/compute/exec#

Execute inside an owned remote sandbox

Auth: Wallet token · Returns 200

Request body

FieldTypeNotes
id requiredstring
command requiredstring
timeoutinteger1–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

Auth: Wallet token · Returns 200

Request body

FieldTypeNotes
id requiredstring
path requiredstring
content_base64 requiredstring

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

Auth: Wallet token · Returns 200

Request body

FieldTypeNotes
id requiredstring
path requiredstringAbsolute path in the sandbox.

Response

JSON object.

POST/v1/transfer/credentials#

Issue temporary S3 credentials for direct transfers within a wallet folder

Auth: Wallet token · Returns 200

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

FieldTypeNotes
prefixstringRelative 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_secondsintegerSession lifetime: 8 hours by default and maximum, capped by wallet expiry. 1–28800. default 28800.

Response · TransferCredentials

FieldTypeNotes
endpoint_url requiredstring (uri)R2 S3 API endpoint; file bytes travel directly here.
region required"auto"
bucket requiredstring
prefix requiredstringFull permitted object prefix, including the wallet ID and trailing slash.
s3_uri requiredstrings3://bucket/prefix/ for native S3 clients. spin s5cmd maps s3://spin/ to this value.
permission required"read-only" | "read-write"
expires_at requiredstring (date-time)
expires_seconds requiredinteger1–28800.
access_key_id requiredstringTemporary session access key ID. Use all three credential fields together.
secret_access_key requiredstringSensitive temporary secret; never log it. The parent secret is never returned.
session_token requiredstringSensitive R2 session token; required on every S3 request. Never log it.

POST/v1/openrouter/key#

Get wallet-scoped key and OpenAI-compatible base_url

Auth: Wallet token · Returns 200

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

Auth: Wallet token · Idempotency-Key header required · Returns 200

Request body

FieldTypeNotes
model requiredstring
messages requiredobject[]
max_tokensintegermin 1.
streambooleanRelay server-sent events as they arrive; the final usage chunk carries the billed cost. default false.
providerobjectOpenRouter 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

Auth: Wallet token · Returns 200

Response

JSON object.