GPUwerk API reference

Everything the console itself calls is reachable at https://api.gpuwerk.com/v1/. This page documents the surface a customer can call with their own credential: how to authenticate, every endpoint and what it returns, the error codes it can actually produce, the rate limits in front of it, and what a /v1/ version guarantee means here.

Authentication

Every authenticated call sends Authorization: Bearer <token>. Three kinds of token are accepted:

An API key is created from the console (or by calling POST /v1/api-keys with a session token) and shown exactly once at creation; only a hash is stored afterward, so a lost key cannot be recovered, only revoked and replaced. A key carries a subset of four scopes: read, instances, billing, inference. Each endpoint below states which scope it needs. A key can never manage other API keys or SSH keys on the account, those two areas require a full session token, so a leaked key cannot mint itself broader access.

A request with a missing or invalid token gets 401. A request with a valid token that lacks the required scope gets 403.

Error shape

Errors are JSON with a single detail field and an HTTP status that means what it says:

Rate limits

Every route is metered by a token bucket, keyed by API key or session token where one is sent, by 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.

Where two prefixes match, the longer one wins, so an instance's terminal or VNC session mint uses its own tighter bucket rather than the general instances one. Twenty failed authentication attempts (a 401, or a 403 from a bad admin token) from one address in ten minutes also gets that address refused outright until the window passes, independent of the per-route limits above, a valid credential does not undo that.

Public endpoints

These need no token. They exist for the marketing site and the console's pre-login screens, and are safe to call directly.

Instances

All paths below are relative to /v1/instances. Every one operates only on instances the caller's account owns; asking about another account's instance returns 404, not 403, so a scan cannot learn an id exists.

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": "",       # paste a key, or:
  "ssh_key_id": "",           # ...name one already on the account
  "enable_vnc": false
}

Returns the instance object: id, name, type, image, status, rate, spent, host/https_endpoint for image flavors that serve HTTP, an ssh block (host, port, user), a vnc block when enabled, and nodes for a multi-node cluster type. Errors: 422 for an unknown type or image or no SSH key resolvable, 409 when the account is over budget, has insufficient available credit, or every capable node is busy.

POST /v1/instances/<id>/stop

Optional body {"hold": false}, only meaningful on a deployment with hold discounts turned off; ignored otherwise, since every stop holds the node by default so a restart takes seconds instead of a full workspace restore. Returns {"ok": true, "held": true, "rate_fraction": <number>} on a hold, or {"ok": true, "archived_bytes": <n>} on a full offload-and-release. 413 if the workspace is too large to offload; 502 if the node does not respond, in which case the instance and its data stay exactly where they were.

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 always requires a full session token (the legacy or SSO account credential), never another API key, a key can never mint or see other keys.

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

Also session-token only, for the same reason as API keys: a credential that could register an SSH key would grant root on every future deploy.

Account

Billing

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

Invoices

Both require the read scope.

Reservations

The authenticated half of the "Reserve Sparks" flow; the public quote and unauthenticated submit are listed under Public endpoints above. All need the billing scope.

Waitlist

All paths relative to /v1/waitlist, needing instances scope for join/leave and read for status.

Versioning and deprecation

Every path is under /v1/. While a route stays on /v1/, we do not remove a field from a response, change what an existing field means, or turn an optional request field into a required one. Fields are added over time, and a client that ignores fields it does not recognize keeps working.

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.