Docs/Reference
Reference

GPUwerk API reference

By Samuel Seidel · Updated November 15, 2026 · 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.

On this page
  1. Authentication
  2. Error shape
  3. Rate limits
  4. Public endpoints
  5. Instances
  6. API keys
  7. SSH keys
  8. Account
  9. Billing
  10. Invoices
  11. Reservations
  12. Waitlist
  13. Hosting (your machines)
  14. Versioning and deprecation

Authentication

Send Authorization: Bearer <token> on every authenticated call. Three kinds of token work:

TokenObtainedScope
Supabase session JWTSigned in through the console (GitHub, Google or email)Full account access; cannot be scoped down
sy_key_… API keyPOST /v1/api-keys, signed in onlyWhichever scopes you grant it at creation
sy_live_… legacy tokenIssued to accounts created before SSO; nothing new issues oneFull 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:

StatusMeaning
400A reservation configuration the quote rules do not allow (cluster size, quantity or term)
401Missing or invalid bearer token
402Not enough available credit for the operation (one hour of runtime to deploy, 15 minutes to start), or the monthly budget is reached
403Token is valid but lacks the scope, or the resource belongs to a different account
404No such resource, or a resource that exists but belongs to someone else (deliberately indistinguishable from the caller's side)
409The 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
422Request body failed validation (unknown type, out-of-range amount, malformed field)
429Rate limited; see below
502The node or an upstream payment call did not respond as expected; usually safe to retry
503Temporarily 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 prefixLimit
/v1/ (default, everything not listed below)300 requests / 60 s
/v1/instances60 / 60 s
/v1/instances/<id>/terminal-sessions10 / 60 s
/v1/instances/<id>/vnc-sessions30 / 60 s
/v1/api-keys30 / 60 s
/v1/billing/checkout10 / 60 s
/v1/signup5 / 3600 s
/v1/reservations (public submit)5 / 3600 s
/v1/reservations/terms, /v1/reservations/quote60 / 60 s
GET /v1/reservations/me60 / 60 s
POST /v1/reservations/me20 / 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.

EndpointReturns
GET /v1/pricingPer-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/statusComponent 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/capacityWithout 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/configPublic 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/imagesThe container flavors currently offered
GET /v1/reservations/termsCluster sizes, discount ladder and self-serve limits the Reserve configurator offers
GET /v1/reservations/quote?cluster_size&quantity&term_monthsEffective hourly rate, monthly price and deposit for a reservation configuration; 400 on an invalid combination
POST /v1/reservationsSubmit 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.

EndpointScopePurpose
GET /v1/instancesreadList every instance on the account
GET /v1/instances/<id>readOne instance: the same object the list returns
POST /v1/instancesinstancesDeploy a new instance
POST /v1/instances/<id>/startinstancesBring a stopped or held instance back onto hardware
POST /v1/instances/<id>/stopinstancesQuiesce the container and hold its node
POST /v1/instances/<id>/restartinstancesRestart the running container in place
POST /v1/instances/<id>/reset-accessinstancesReinstall account SSH keys and a known-good sshd config (pasting a new key needs a signed-in session)
POST /v1/instances/<id>/rebuildinstancesRecreate the container from a different image (pasting a new key needs a signed-in session)
DELETE /v1/instances/<id>instancesTerminate the instance permanently
GET /v1/instances/<id>/metrics?rangereadCPU/GPU/memory time series, live or historical
GET /v1/instances/<id>/logs?tailreadThe tenant container's stdout/stderr
GET /v1/instances/<id>/diskreadDurable workspace bytes vs. container writable-layer bytes
GET /v1/instances/<id>/eventsreadLast 50 lifecycle events for the instance
GET /v1/instances/<id>/authorize-modelinferenceGateway pre-check that a model endpoint is reachable; not meant to be called directly
POST /v1/instances/<id>/vnc-sessionsinstancesMint a single-use token for the browser VNC viewer
POST /v1/instances/<id>/terminal-sessionssigned-in sessionMint a single-use token for the browser terminal
DELETE /v1/instances/<id>/terminal-sessions/<session_id>instancesClose 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:

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.

EndpointPurpose
GET /v1/api-keysList keys on the account, optionally filtered by instance_id
POST /v1/api-keysCreate 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.

EndpointPurpose
GET /v1/ssh-keysList keys stored on the account
POST /v1/ssh-keysRegister 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

EndpointAuthPurpose
GET /v1/meany credentialCredit balance, available credit, burn rate, remaining trial hours, budget
GET/PUT /v1/account/budgetsession for PUTMonthly spend cap
GET/PUT /v1/account/billing-profilesession for PUTInvoice 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/exportsessionMachine-readable export of the account's own data
GET/POST/DELETE /v1/account/closuresessionCheck, request, or cancel account closure

Billing

All paths below are relative to /v1/billing and need the billing scope.

EndpointPurpose
POST /checkoutCreate 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 /paymentsLast 100 top-up attempts with status
GET /ledgerFull account statement: every credit and debit, newest first, with the running balance
GET/PUT /auto-topupRead 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_usdThe exact mandate text for the chosen amounts, so what is shown and what is stored as evidence cannot drift apart
GET /v1/billing/transactionsLegacy statement shape the console still reads (note: one /billing, not two); prefer GET /ledger

Invoices

EndpointPurpose
GET /v1/invoicesList invoices with amounts and a ready flag
GET /v1/invoices/<id>.pdfPDF invoice; renders on demand if not yet generated, 503 while preparing
GET /v1/invoices/<id>.xmlUBL 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.

EndpointPurpose
GET /v1/reservations/meThis account's reservation requests, including ones submitted before sign-in that matched by email
POST /v1/reservations/meSubmit a reservation request as the signed-in account; 202 with the created request and its quote
POST /v1/reservations/<id>/depositCreate 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-cardStripe-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.

EndpointPurpose
POST /v1/waitlistJoin the line for a node type: {"type": "spark-1x", "expected_hours": null}; 409 if capacity is already free
DELETE /v1/waitlist?type=spark-1xLeave the line
GET /v1/waitlist/meThis 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.

EndpointScopePurpose
GET /v1/partner/nodesreadYour machines: state, rented or not, reliability, hours and earnings this month
GET /v1/partner/telemetryreadGPU 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>/telemetryreadThe same for one machine
GET /v1/partner/metricsreadPrometheus 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=30readRented hours and rentals per day
GET /v1/partner/mereadYour host account and its status
GET /v1/partner/earnings, /statements, /payouts, /payouts.csvbillingEarnings, 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.

NextCreate an SSH key and connect Back toAll docs
First top-up: pay $20, get $30 in credit

Get an API key with your first top-up.

A dedicated DGX Spark in Europe, North America or East Asia, through the console.

Create account