GPUwerk API reference
The GPUwerk API lives at https://api.gpuwerk.com/v1/, and the console uses the same endpoints. This page covers what you can call with your own credential: how to authenticate, each endpoint and its scope, the errors it returns, the rate limits, and what the /v1/ version promise covers.
What is listed. Only endpoints you can reach with your own session token or API key. Operator and admin routes, dev-only login routes, the Stripe webhook and the internal callbacks nodes use to move a workspace are left out. If an endpoint is not on this page, treat it as unsupported, even if you see it in a console network trace.
Authentication
Send Authorization: Bearer <token> on every authenticated call. Three kinds of token work:
| Token | Obtained | Scope |
|---|---|---|
| Supabase session JWT | Signed in through the console (GitHub, Google or email) | Full account access; cannot be scoped down |
sy_key_… API key | POST /v1/api-keys, signed in only | Whichever scopes you grant it at creation |
sy_live_… legacy token | Issued to accounts created before SSO; nothing new issues one | Full account access |
Create an API key in the console, or call POST /v1/api-keys with a session token. The key is shown once. GPUwerk stores only a hash, so a lost key cannot be recovered: revoke it and create a new one.
A key carries one or more of four scopes: read, instances, billing, inference. Each endpoint below names the scope it needs. Some account operations accept a session token only: managing API keys and SSH keys, changing the budget or billing profile, the account export and account closure. A leaked key therefore cannot create broader access for itself.
A missing or invalid token gets 401. A valid token without the required scope gets 403.
Error shape
An error is JSON with a detail field (usually a sentence you can show to a person) and one of these statuses:
| Status | Meaning |
|---|---|
400 | A reservation configuration the quote rules do not allow (cluster size, quantity or term) |
401 | Missing or invalid bearer token |
402 | Not enough available credit for the operation (one hour of runtime to deploy, 15 minutes to start), or the monthly budget is reached |
403 | Token is valid but lacks the scope, or the resource belongs to a different account |
404 | No such resource, or a resource that exists but belongs to someone else (deliberately indistinguishable from the caller's side) |
409 | The request is valid but the resource is in the wrong state for it: no free capacity for the type, an instance mid-operation, an instance not running yet, a reservation already deposited |
422 | Request body failed validation (unknown type, out-of-range amount, malformed field) |
429 | Rate limited; see below |
502 | The node or an upstream payment call did not respond as expected; usually safe to retry |
503 | Temporarily unavailable: no public IPv4 address is free yet (with Retry-After), an invoice is still being prepared, or a feature such as card payments is not configured |
Rate limits
Every route has a token-bucket limit, counted per API key or session token when one is sent and per IP address otherwise. A request over the limit gets 429 with a JSON body of {"detail": "too many requests"} and a Retry-After header giving the number of seconds to wait before trying again.
| Path prefix | Limit |
|---|---|
/v1/ (default, everything not listed below) | 300 requests / 60 s |
/v1/instances | 60 / 60 s |
/v1/instances/<id>/terminal-sessions | 10 / 60 s |
/v1/instances/<id>/vnc-sessions | 30 / 60 s |
/v1/api-keys | 30 / 60 s |
/v1/billing/checkout | 10 / 60 s |
/v1/signup | 5 / 3600 s |
/v1/reservations (public submit) | 5 / 3600 s |
/v1/reservations/terms, /v1/reservations/quote | 60 / 60 s |
GET /v1/reservations/me | 60 / 60 s |
POST /v1/reservations/me | 20 / 3600 s |
When two prefixes match, the longer one wins, so terminal and VNC session mints use their own tighter bucket, not the general instances one.
Separately, 20 failed authentications (a 401, or a 403 from a bad admin token) from one address within ten minutes block that address until the window passes. Sending a valid credential during the block does not lift it.
Public endpoints
No token needed. The website and the console's signed-out screens use these, and you can call them directly.
| Endpoint | Returns |
|---|---|
GET /v1/pricing | Per-hour rate, units and hardware class for each instance type, and whether it is rentable today (available) or only planned, with a waitlist (planned); deployable is whether a deploy would be placed right now, the same answer as /v1/capacity |
GET /v1/status | Component health, whether each instance type is available (available, yes or no) and, per type, how long the people now on its waitlist have waited (waitlist.avg_wait_s, waitlist.max_wait_s, or null when nobody is waiting). No free count and no fleet size. |
GET /v1/capacity | Without a token: whether a rental can start, overall and per instance type (available only). With a token: the counts the console uses (free machines, locations, which images can start). |
GET /v1/config | Public console configuration: Supabase project, top-up bonus terms, hold-rate fraction, how long a workspace stays on its released machine after credit or budget runs out (exhausted_keep_hours) |
GET /v1/images | The container flavors currently offered |
GET /v1/reservations/terms | Cluster sizes, discount ladder and self-serve limits the Reserve configurator offers |
GET /v1/reservations/quote?cluster_size&quantity&term_months | Effective hourly rate, monthly price and deposit for a reservation configuration; 400 on an invalid combination |
POST /v1/reservations | Submit an unauthenticated reservation request; 202, rate-limited at 5/hour |
Instances
Every endpoint acts only on instances your account owns. Asking about another account's instance returns 404, not 403, so nobody can probe which ids exist.
| Endpoint | Scope | Purpose |
|---|---|---|
GET /v1/instances | read | List every instance on the account |
GET /v1/instances/<id> | read | One instance: the same object the list returns |
POST /v1/instances | instances | Deploy a new instance |
POST /v1/instances/<id>/start | instances | Bring a stopped or held instance back onto hardware |
POST /v1/instances/<id>/stop | instances | Quiesce the container and hold its node |
POST /v1/instances/<id>/restart | instances | Restart the running container in place |
POST /v1/instances/<id>/reset-access | instances | Reinstall account SSH keys and a known-good sshd config (pasting a new key needs a signed-in session) |
POST /v1/instances/<id>/rebuild | instances | Recreate the container from a different image (pasting a new key needs a signed-in session) |
DELETE /v1/instances/<id> | instances | Terminate the instance permanently |
GET /v1/instances/<id>/metrics?range | read | CPU/GPU/memory time series, live or historical |
GET /v1/instances/<id>/logs?tail | read | The tenant container's stdout/stderr |
GET /v1/instances/<id>/disk | read | Durable workspace bytes vs. container writable-layer bytes |
GET /v1/instances/<id>/events | read | Last 50 lifecycle events for the instance |
GET /v1/instances/<id>/authorize-model | inference | Gateway pre-check that a model endpoint is reachable; not meant to be called directly |
POST /v1/instances/<id>/vnc-sessions | instances | Mint a single-use token for the browser VNC viewer |
POST /v1/instances/<id>/terminal-sessions | signed-in session | Mint a single-use token for the browser terminal |
DELETE /v1/instances/<id>/terminal-sessions/<session_id> | instances | Close a browser terminal session |
POST /v1/instances
Request body:
{
"name": "", # optional, autogenerated if blank
"type": "spark-1x", # a key from GET /v1/pricing
"image": "dgx-os", # a key from GET /v1/images
"ssh_public_key": "", # optional: paste a key (signed-in session only), or:
"ssh_key_id": "", # ...name one already on the account
"enable_vnc": false,
"allow_partner": false, # spark-1x only: true also takes a partner's DGX Spark when none of GPUwerk's own is free (Terms §18)
"partner_region": "eea", # "eea" (default): only a machine in the EEA; "any": anywhere, which can transfer your data outside the EU/EEA (Terms §18)
"location_country": "", # optional: only a machine in this country (ISO 3166-1 alpha-2, e.g. "DE")
"location_region": "", # optional: europe, north_america, south_america, africa, middle_east or asia_pacific
"max_lifetime_minutes": null # optional: 10 to 43200 (30 days); terminated when the time is up
}
Returns the instance object: id, name, type, image, status, rate, spent, host/https_endpoint for image flavors that serve HTTP, with https_termination (instance: TLS ends on the machine; gateway: TLS ends at Cloudflare and the GPUwerk gateway; null: no endpoint), an ssh block (host, port, user), a vnc block when enabled, and nodes, one entry per machine the instance holds. Each entry has a location: country, country_name, region, region_name, in_eea and notice, the sentence the console shows, for example "This machine is located in Czechia (EEA)." terminate_at is when the instance will be terminated (epoch seconds), or null when you set no limit.
max_lifetime_minutes sets a deadline, counted from the deploy request. When it passes, GPUwerk terminates the instance and deletes its workspace, the same as DELETE /v1/instances/<id>. This happens whatever its status, including stopped, because a stopped instance is still billed. The one exception is an account in its switching retrieval period (Terms §19), whose instances are kept. Copy out anything you want to keep before then. It is checked about once a minute, so an instance can run a little past its deadline; you pay for that time. The deadline cannot be changed after the deploy. Use it so an unattended job, such as a CI run, cannot leave an instance running if the job fails.
allow_partner is off unless you send it. With false a spark-1x deploy runs only on a DGX Spark GPUwerk owns, in our EU-Central data center. With true it still takes one of ours while one is free, and otherwise a free DGX Spark that an independent partner hosts at their own premises, in the location partner_region and the location filter allow. That instance is the Partner tier (type spark-1x-partner, same hourly rate as spark-1x today; GET /v1/pricing lists both): the partner has physical access to the machine and there is no SLA, as Terms §18 describes. The console's location choices that include partner Sparks send true.
You do not need an SSH key to deploy. GPUwerk configures the machine, and the console's browser terminal works without a key. With neither SSH field set, the account's newest registered key is installed if there is one; otherwise the instance starts without a customer key, and you can add one later with reset-access.
Errors:
422: unknowntypeorimage, amax_lifetime_minutesoutside 10 to 43200, a pasted key that is not a valid public key, an unknownlocation_countryorlocation_region, a country outside the region you named, or a country outside the EEA withpartner_region"eea".403: a pastedssh_public_keysent with an API key. A pasted key gives root on the instance, so it needs a signed-in session; save the key on the account withPOST /v1/ssh-keysand deploy with itsssh_key_id.404: thessh_key_idis not on this account.402: not enough available credit for one hour at the type's rate, or the monthly budget is reached.409: no free machine of that type right now, or none in the location you asked for. Join the waitlist to be emailed when one frees up. When aspark-1xdeploy withoutallow_partneris refused while a partner's DGX Spark it could take is free,detailis an object withcode"partner_spark_free", amessage,opt_in({"allow_partner": true}),partner_type,partner_country,partner_in_eea,partner_rateandrate(the hourly rate you asked for). Send the same request with"allow_partner": trueto take that machine. Nothing was created or charged.503: no public IPv4 address is free yet. Nothing was created or charged; retry after theRetry-Afterseconds.
POST /v1/instances/<id>/stop
No body needed. Every stop holds the machine: the container stops, the workspace stays on the node, and the instance is billed at a fraction of its hourly rate (hold_rate_fraction in GET /v1/pricing). Starting again takes seconds. The workspace is never copied off the node. Response: {"ok": true, "held": true, "rate_fraction": <number>, "note": "..."}. The optional {"hold": false} body is ignored.
Running out of credit or reaching the monthly budget stops an instance differently: its machine is released and the workspace stays on it until someone else rents the machine, or for up to exhausted_keep_hours. While that is so, the instance has status stopped and parked_until (epoch seconds) says when the workspace is deleted at the latest; otherwise parked_until is null.
If the node does not quiesce the container, the instance is left in the state it was in and the request fails.
GET /v1/instances/<id>/metrics
range is one of live, 1h, 6h, 24h, 7d; anything else is a 422. live on a stopped instance falls back to the last hour of stored history rather than an empty series.
API keys
Managing keys requires a session token (or a legacy account token). An API key can never list, create or revoke keys.
| Endpoint | Purpose |
|---|---|
GET /v1/api-keys | List keys on the account, optionally filtered by instance_id |
POST /v1/api-keys | Create a key; the token is returned once, in this response only |
DELETE /v1/api-keys/<id> | Revoke a key |
POST /v1/api-keys body: {"name": "", "scopes": ["read","instances"], "instance_id": null}. Passing instance_id creates a key scoped to only the inference scope against that one instance, regardless of what scopes asked for; omit it for an account-wide key restricted to the requested subset of read, instances, billing, inference. 422 if the requested scopes intersect with none of those four.
SSH keys
Session token only, for the same reason: a credential that can register an SSH key gets root on every future deploy.
| Endpoint | Purpose |
|---|---|
GET /v1/ssh-keys | List keys stored on the account |
POST /v1/ssh-keys | Register a public key: {"name": "", "public_key": "ssh-ed25519 ..."} |
DELETE /v1/ssh-keys/<id> | Remove a key from the account (does not revoke access already baked into a running instance's authorized_keys) |
Account
| Endpoint | Auth | Purpose |
|---|---|---|
GET /v1/me | any credential | Credit balance, available credit, burn rate, remaining trial hours, budget |
GET/PUT /v1/account/budget | session for PUT | Monthly spend cap |
GET/PUT /v1/account/billing-profile | session for PUT | Invoice address, VAT id, invoicing details. A VAT id is checked in the EU VIES register when saved; the response includes vat_check (status: verified, invalid, unavailable, unsupported or none, plus the registered name when verified) |
GET /v1/account/export | session | Machine-readable export of the account's own data |
GET/POST/DELETE /v1/account/closure | session | Check, request, or cancel account closure |
Billing
All paths below are relative to /v1/billing and need the billing scope.
| Endpoint | Purpose |
|---|---|
POST /checkout | Create a Stripe Checkout session for a top-up: {"amount_usd": 25, "save_card": false} → {"checkout_url": "..."}. 422 outside the configured min/max; 503 if card payments are not enabled |
GET /payments | Last 100 top-up attempts with status |
GET /ledger | Full account statement: every credit and debit, newest first, with the running balance |
GET/PUT /auto-topup | Read or configure automatic top-up (enabled, amount_usd, threshold_usd, mandate_accepted); enabling without a saved card returns needs_card: true rather than an error |
GET /auto-topup/mandate?amount_usd&threshold_usd | The exact mandate text for the chosen amounts, so what is shown and what is stored as evidence cannot drift apart |
GET /v1/billing/transactions | Legacy statement shape the console still reads (note: one /billing, not two); prefer GET /ledger |
Invoices
| Endpoint | Purpose |
|---|---|
GET /v1/invoices | List invoices with amounts and a ready flag |
GET /v1/invoices/<id>.pdf | PDF invoice; renders on demand if not yet generated, 503 while preparing |
GET /v1/invoices/<id>.xml | UBL 2.1 XML invoice for accounting software |
Both require the read scope.
Reservations
The signed-in part of the Reserve flow. The public quote and the signed-out submit are under Public endpoints. All of these need the billing scope.
| Endpoint | Purpose |
|---|---|
GET /v1/reservations/me | This account's reservation requests, including ones submitted before sign-in that matched by email |
POST /v1/reservations/me | Submit a reservation request as the signed-in account; 202 with the created request and its quote |
POST /v1/reservations/<id>/deposit | Create the Stripe Checkout session for the flat deposit; 403 if the request belongs to a different account, 409 if a deposit is already paid or availability is unconfirmed |
POST /v1/reservations/<id>/authorize-card | Stripe-hosted page to save or replace the card charged for monthly billing |
Waitlist
Joining and leaving need the instances scope; reading your entries needs read.
| Endpoint | Purpose |
|---|---|
POST /v1/waitlist | Join the line for a node type: {"type": "spark-1x", "expected_hours": null}; 409 if capacity is already free |
DELETE /v1/waitlist?type=spark-1x | Leave the line |
GET /v1/waitlist/me | This account's current waitlist entries, one per line it is on; auto_added is true for an entry GPUwerk added automatically when the account signed up, not one the account joined itself; joining that line again sets it to false. Leave one with DELETE /v1/waitlist?type= |
Hosting (your machines)
If you host machines on GPUwerk, an API key can read them for your own monitoring. The key's account must be a member of the host account, and the member role still applies: earnings need the owner or finance role. Everything that changes a machine (pairing, maintenance, unlisting, using it yourself), agreements, payout details and members take a signed-in session only. A key created for one instance never reads these.
| Endpoint | Scope | Purpose |
|---|---|---|
GET /v1/partner/nodes | read | Your machines: state, rented or not, reliability, hours and earnings this month |
GET /v1/partner/telemetry | read | GPU temperature and power of each machine, live: the latest reading, the last few minutes at 2.5 s and the highest temperature in them. reachable is false when a machine did not answer. Readings are cached for 15 s |
GET /v1/partner/nodes/<id>/telemetry | read | The same for one machine |
GET /v1/partner/metrics | read | Prometheus text: gpuwerk_node_up, gpuwerk_node_gpu_temperature_celsius and gpuwerk_node_gpu_power_watts, labelled node_id and name. Scrape it with the key as the bearer token |
GET /v1/partner/usage?days=30 | read | Rented hours and rentals per day |
GET /v1/partner/me | read | Your host account and its status |
GET /v1/partner/earnings, /statements, /payouts, /payouts.csv | billing | Earnings, monthly statements and payouts |
Telemetry is GPU temperature and power only. GPU use, memory and network are not available to hosts, because while a machine is rented they would show what the renter is doing.
A Prometheus scrape job, with the key in a file:
- job_name: gpuwerk
scheme: https
metrics_path: /v1/partner/metrics
scrape_interval: 30s
authorization:
credentials_file: /etc/prometheus/gpuwerk-key
static_configs:
- targets: [api.gpuwerk.com]
Versioning and deprecation
Every path is under /v1/. While a route stays on /v1/, GPUwerk does not remove a response field, change what an existing field means, or make an optional request field required. New fields get added, so write clients that ignore fields they do not recognize.
A change that would break that contract, such as removing an endpoint or replacing it with a different shape, ships as a new version prefix rather than as a silent change to /v1/, with advance notice before /v1/ itself is retired. There is no fixed notice period published yet; check this page and the status page before relying on one.
This page does not promise an SLA, an uptime figure or a support response time; see the terms for what is and is not warranted.