API reference

Listed offers on available, admitted machines with a heartbeat in the last 90 seconds; only these can be reserved. Server-side filters are model, gpu_count, max_rate_micro_per_hour, verification_level, continent and template_id; sort defaults to price_asc, and near puts one continent's machines first. There is no VRAM, region, RAM, disk or bandwidth filter: each item carries vram_bytes, region, ram_bytes and disk_bytes when measured, for client-side filtering. With template_id (D-19(c)) every item carries a server-computed fit object. No cached public responses.

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Page of offer summaries. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/offers"

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Offer summary. (OfferSummary)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/offers/<id>"

D-19(c). Cursor paged; filters kind and min_vram_bytes (templates whose vram_fit.min_vram_bytes <= the given value). Only published templates (bound to at least one admitted machine by a qualification record) are listed. No cached public responses.

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Page of templates. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/templates"

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Template. (Template)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/templates/<templateId>"

Returns an immutable quote with 60s expiry, terms version, machine manifest hash and total rate. Refresh stale catalog quotes before charging. Quoting is free and holds nothing; POST /api/v1/jobs reserves. The Idempotency-Key is not deduplicated on this route, so a retry returns a fresh quote. 409 CONFLICT when the offer's machine is not admitted: an unverified listing (OfferSummary admitted false) is shown but cannot be quoted or reserved until it passes qualification.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 201 — Immutable quote. (Quote)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/quotes" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"offer_id":"8b0c2f4e-1d3a-4c5b-9e6f-7a8b9c0d1e2f","template_id":"a35d15fe-ab57-4283-87f8-a00528d1d631","duration_limit_s":7200,"budget_micro":"1000000"}'

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Page of jobs. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/jobs" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Atomically holds budget, reserves machine, increments fence and queues start. Rejects expired quote (409 QUOTE_EXPIRED), changed manifest, unavailable or not admitted machine, or insufficient spendable funds (409 INSUFFICIENT_FUNDS) without partial holds. Replaying the same Idempotency-Key with the same body returns the original job, so a timed-out request is safe to retry; the same key with another body is 409 IDEMPOTENCY_CONFLICT and reserves nothing.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Job reserved. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/jobs" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"0c1d2e3f-4a5b-4c6d-8e7f-8091a2b3c4d5","ssh_public_key":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGVxYW1wbGVrZXlfbm90X3JlYWw you@laptop"}'

Poll this after POST /api/v1/jobs. States run RESERVED -> STARTING -> RUNNING (verified ready; the meter starts here) -> STOPPING -> STOPPED -> CLEANING -> CLOSED, or FAILED / RECONCILING. GET /api/v1/jobs/{id}/access answers only while RUNNING (execution) or, for a limited window, after STOPPED (read-only retrieval); other states are 403.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Job detail. (Job)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/jobs/<id>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Page of sequenced events. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/jobs/<id>/events" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Execution access only while ready/running; STOPPED retrieval access is read-only, time-limited and explicitly labeled. No execution endpoint before verified readiness.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Access material. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/jobs/<id>/access" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

One of four relay paths (models, chat/completions, completions, embeddings); any other path under /openai/v1 is 404. The server forwards to the rental's own leased http endpoint and adds the per-job key; client cookies and Authorization never reach the host. 409 unless the job is RUNNING with a model endpoint. Bodies over 1 MiB are 413. Rate-limited per account. Point any OpenAI client here as its base URL with an AmpleRun API key (renter scope).

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — The engine's model list, passed through. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/jobs/<id>/openai/v1/models" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Same rules as the models path. With stream:true the response is text/event-stream, streamed unbuffered.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Request body (application/json): object

Responses

• 200 — The engine's response, passed through (JSON, or SSE when stream:true). (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/jobs/<id>/openai/v1/chat/completions" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"Qwen/Qwen3-32B-AWQ","stream":true,"messages":[{"role":"user","content":"hello"}]}'

Same rules as the models path; stream:true streams text/event-stream.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Request body (application/json): object

Responses

• 200 — The engine's response, passed through. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/jobs/<id>/openai/v1/completions" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '"string"'

Same rules as the models path.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Request body (application/json): object

Responses

• 200 — The engine's response, passed through. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/jobs/<id>/openai/v1/embeddings" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '"string"'

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 202 — STOPPING or original terminal result. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/jobs/<id>/stop" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"training finished"}'

Idempotent. Appends one immutable amendment plus hold atomically; keeps original rate and snapshotted host-availability ceiling; bumps budget_version. Rejects once STOPPING begins. D-16 — budget_version changes only with a committed funding amendment.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Amendment committed; returns new budget_version. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/jobs/<id>/budget-extension" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"additional_budget_micro":"5000000","new_duration_limit_s":1,"expected_job_version":"1","expected_budget_version":"1"}'

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 200 — Fresh quote parameters. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/jobs/<id>/rerun" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Currently composed providers; credentials are never returned. (object)

Example

curl -X GET "https://amplerun.com/api/v1/auth/providers"

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Account profile. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/account" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

role_preference is rent, host or both. It changes navigation emphasis only. Renting and hosting stay available. Completes role onboarding.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Saved. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X PATCH "https://amplerun.com/api/v1/account" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role_preference":"rent"}'

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Delegation rows
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/account/delegations" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

The owner sends agent_account_id and the grant is approved immediately. The agent sends owner_account_id and the row stays pending until the owner approves. Scopes are machines:enroll, machines:read, offer:price, machines:listing, machines:status, earnings:read, payouts:read. Withdrawals, wallets, payout destinations and machine transfer are refused.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 201 — Owner grant
• 202 — Agent request
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/account/delegations" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_account_id":"string","owner_account_id":"string","scopes":["string"]}'

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Approved.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/account/delegations/<id>/approve" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Revoked. Repeating a revoke stays revoked.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/account/delegations/<id>/revoke" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Active sessions.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/account/sessions" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Deleting the session row is the revocation. A session the caller does not own is indistinguishable from a missing one (404). API-key callers have no sessions (404).

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 204 — Revoked.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X DELETE "https://amplerun.com/api/v1/account/sessions/<id>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — API key metadata; secrets never re-shown. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/account/api-keys" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Label, expiry and explicit renter/host scopes. Secret revealed once; only hash stored. No admin scopes or key-based MFA bypass.

Auth

Session cookie or API key with the renter scope; recent step-up (POST /api/v1/account/step-up) required

Idempotency-Key

required (UUID header)

Responses

• 201 — API key created; secret returned exactly once. (unknown)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/account/api-keys" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"label":"string","expires_at":"2026-09-25T12:00:00Z","scopes":["renter"]}'

Auth

Session cookie or API key with the renter scope; recent step-up (POST /api/v1/account/step-up) required

Idempotency-Key

required (UUID header)

Responses

• 204 — Revoked.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X DELETE "https://amplerun.com/api/v1/account/api-keys/<id>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Whether a per-user token is on file for this provider; never the value.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Token status. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/account/integrations/<provider>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Encrypted at rest the same way as an admin secret setting; never re-shown once saved.

Auth

Session cookie or API key with the renter scope; recent step-up (POST /api/v1/account/step-up) required

Idempotency-Key

required (UUID header)

Responses

• 201 — Token stored.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/account/integrations/<provider>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"string"}'

Auth

Session cookie or API key with the renter scope; recent step-up (POST /api/v1/account/step-up) required

Idempotency-Key

required (UUID header)

Responses

• 204 — Removed.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X DELETE "https://amplerun.com/api/v1/account/integrations/<provider>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Export job persisted.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/account/export" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Deletion request persisted.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/account/deletion-request" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Returns a server-written Sign-In with Ethereum (EIP-4361) message for this address: this deployment's domain and URI, Base (chain 8453), a single-use nonce and a five-minute expiry. Its statement carries the Terms version the agent accepts by signing. Sign it exactly as returned (EIP-191 personal_sign) with the wallet's key. EOA wallets only. Rate-limited per source address and per wallet. Not /api/v1/agents/enroll, which enrolls host machines.

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — The message to sign. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/agents/accounts/challenge" \
  -H "Content-Type: application/json" \
  -d '{"address":"string"}'

Verifies the signed challenge (single use, unexpired, byte-for-byte the message the server wrote, signed by its address) and opens an account tagged account_kind agent, with the wallet as its verified linked wallet and payout destination. Returns an API key with the renter and host scopes unless scopes names a subset, shown once. The same wallet again returns the same account (200) and a new key, only with a fresh signature. There is no free credit: fund the account (POST /api/v1/funding-intents) before renting. Refused: a replayed, expired or tampered message (401); a wallet linked to or unlinked from another account, or an account with an authenticator app (409); a suspended account's wallet (403). Rate-limited per source address and per wallet (429). Audited.

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — The agent's account (201 new, 200 existing) and a new API key. The secret is shown only here. (object)
• 201 — The agent's account (201 new, 200 existing) and a new API key. The secret is shown only here. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/agents/accounts" \
  -H "Content-Type: application/json" \
  -d '{"message":"string","signature":"string","agent":{"name":"string","vendor":"string","model":"string","operator_contact":"string","homepage":"string"},"scopes":["renter"]}'

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Wallet bindings. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/wallets" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Five-minute single-use nonce with exact origin/URI, chain, issued/expiration time and server-session binding.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 201 — Single-use nonce. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/wallets/nonce" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Binds chain/address to account; nonce consumed once. UNIQUE(chain_id,address) across accounts.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 201 — Binding created. (WalletBinding)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/wallets/link" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"chain_id":8453,"address":"0x1111111111111111111111111111111111111111","siwe_message":"string","signature":"string"}'

Blocks future use but retains historical attribution and pending-intent versions; old transfers cannot become claimable by another account.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 204 — Unlinked.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X DELETE "https://amplerun.com/api/v1/wallets/<binding_id>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Chain 8453/USDC to treasury address/token, exact network, expiry and noncustodial-send instructions. No private key collection.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 201 — Funding intent. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/funding-intents" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"wallet_binding_id":"3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40","amount_micro":"5000000"}'

Read-only; never claims or credits. While a recorded transfer awaits finality, finalized_block_number is the RPC's finalized head (null when the RPC is unreachable). No time estimate is given.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Funding intent. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/funding-intents/<id>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Verifies ERC20 Transfer sender=bound wallet, recipient=treasury, exact token/chain, successful receipt, canonical block and finalized head; PENDING/CONFIRMED/EXCEPTION. A transfer from a wallet not bound to this account is 403 and records nothing on the intent; a transfer not yet visible is PENDING and records nothing. Provider error pauses credit; never zero balance and never success.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Claim state. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/funding-intents/<id>/claim" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"tx_hash":"string","log_index":0}'

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Balances. (BalanceSet)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/billing" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Send USDC or USDT, or the network's own coin (ETH, POL, BNB, AVAX), to `address` on any network in `networks`, from anywhere: an exchange or any wallet. No wallet linking and no transaction hash are needed. Each stablecoin transfer is credited exactly once, after that network's finality, 1:1. A native coin is credited in USD at the Chainlink price at finality minus `native.spread_bps`. The address never changes. Funds sent on a network not listed in `networks` are not credited. `deposits` lists recent deposits: SEEN (on chain, waiting for finality; display only), CREDITED, or HELD (arrived but over a balance cap; credited automatically once there is room).

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — The deposit address and recent deposits. (DepositAddress)
• 503 — Deposit addresses are not configured on this server.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/billing/deposit-address" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Page of ledger entries with immutable external references and evidence links.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/billing/entries" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Receipt. charge_micro = fee_micro + host_micro, as posted to the ledger. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/billing/receipts/<job>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

x402 v2, scheme exact: an EIP-3009 transferWithAuthorization of native USDC on Base (eip155:8453) straight to the treasury. Without a payment header the answer is 402 with PaymentRequirements (also base64 in the PAYMENT-REQUIRED header). Sign them and repeat the same request with PAYMENT-SIGNATURE (the v1 header name X-PAYMENT is accepted too). The payment itself authorizes the top-up; no Idempotency-Key is needed, and repeating the same payment returns the first result. The credit goes to the API key's account whatever wallet pays, and lands once, after Base finality (state PENDING_FINALITY until then). A 202 means the settlement is broadcast but not mined yet; repeat the same request. 404 while the operator has not enabled x402.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Settled on chain and pinned to this account; credited now (CONFIRMED) or after finality (PENDING_FINALITY). PAYMENT-RESPONSE and X-PAYMENT-RESPONSE carry the base64 SettlementResponse. (X402TopUp)
• 202 — Settlement broadcast, not mined yet. Repeat the same request. (object)
• 402 — Payment required, or the payment was refused (error names the reason, e.g. invalid_amount, authorization_expired). (X402PaymentRequired)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/billing/x402/top-up" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

x402 v2, scheme exact, EIP-3009 USDC. If the account's spendable USDC already covers budget_micro, the rental is reserved and nothing else is charged. Otherwise the answer is 402 for the shortfall only. Signing it credits this account the way a deposit does (one credit per authorization nonce, shared with the top-up route so the same payment cannot settle twice). The rental is reserved once that credit is spendable. Repeat the same body: idempotency_key reserves at most one job. 202 means the settlement is broadcast and not mined yet. PENDING_FINALITY means the payment is pinned and the credit is not spendable yet. Mainnet is omitted from this rental offer unless X402_MAINNET_ENABLED is set. Top-ups are not gated by that flag. 404 while x402 is off. Solana is not accepted.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Rental reserved, or the payment is pinned and waiting until the credit is spendable. (X402Rent)
• 202 — Settlement broadcast, not mined yet. Repeat the same request. (X402Rent)
• 402 — Payment required for the shortfall, or the payment was refused. (X402PaymentRequired)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/billing/x402/rent" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offer_id":"3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40","template_id":"3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40","image_digest":"registry.amplerun.com/templates/pytorch-cuda@sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","image_ref":"string","duration_limit_s":1,"budget_micro":"1","asset":"USDC","ssh_public_key":"string","idempotency_key":"3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40"}'

Locked withdrawal intent to a saved address, or, for an address this account never used, a parked request that the emailed link (30 min) queues unchanged. New addresses are refused for 24 h after a password, 2FA or email change. API keys reach saved addresses only, without a code. No spendable credit while a transfer is pending. `amount_micro` is what leaves the balance: at least the WITHDRAWAL_MIN_MICRO setting (5 USDC by default), of which the WITHDRAWAL_FEE_MICRO fee (0.5 USDC by default) is kept when the withdrawal settles and the rest arrives. A failed withdrawal is not charged.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Queued, or waiting for the email link. (TransferAccepted)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/withdrawals" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"network":"base","address":"0x1111111111111111111111111111111111111111","amount_micro":"5000000","asset":"USDC","label":"string","code":"string","siwe_message":"string","signature":"string"}'

404 while SOLANA_HOT_PAYOUTS_ENABLED is not exactly "true". Queues an SPL USDC withdrawal. SOL is the fee coin and is not paid out. The Ethereum withdrawal route is a different operation. Idempotency-Key replays the same body and rejects a different one. The amount is capped by SOLANA_HOT_MAX_MICRO.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Queued
• 404 — Solana hot payouts are off.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/solana/withdrawals" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount_micro":"string","destination":"string"}'

Bound to kind, network, address, amount and asset; 10 minutes, 5 tries, single use, 5 per hour. 409 for 2FA accounts (use the authenticator).

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 202 — Code sent. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/withdrawals/code" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"withdrawal","network":"base","address":"0x1111111111111111111111111111111111111111","amount_micro":"5000000","asset":"USDC"}'

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Saved and pending addresses. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/withdrawal-addresses" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

2FA accounts also send their authenticator `code`. Needed before API-key withdrawals to a new address. Wallet-only accounts and API keys cannot add addresses.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Link sent (or already saved). (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/withdrawal-addresses" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"network":"base","address":"0x1111111111111111111111111111111111111111","label":"string","code":"string"}'

Bumps its version; an unsigned transfer to it is no longer paid automatically.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Removed. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X DELETE "https://amplerun.com/api/v1/withdrawal-addresses/<id>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Confirms the address and queues the parked withdrawal or payout exactly as requested. Idempotent. Refused after 30 minutes or after a credential change.

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Confirmed. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/withdrawal-addresses/confirm" \
  -H "Content-Type: application/json" \
  -d '{"token":"string"}'

404 while SOLANA_HOT_PAYOUTS_ENABLED is not exactly "true". Queues an SPL USDC host payout. The Ethereum payout route is a different operation.

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Queued
• 404 — Solana hot payouts are off.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/solana/payouts" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount_micro":"string","destination":"string"}'

One-use 10-minute token plus signed release URL/digest and preflight steps. Rate-limited independently.

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 201 — Enrollment material. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/enrollment-tokens" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Called by the one-line installer (`curl -fsSL https://amplerun.com/host | sudo bash`). Returns a short user_code for a person to approve on /pair and a poll_secret only the installer holds; only their hashes are stored. Expires after 10 minutes. The code alone never yields a token. Rate-limited per source address.

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 201 — Pairing opened. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/pairings" \
  -H "Content-Type: application/json" \
  -d '{"summary":{"hostname":"string","os":"string","gpus":[{"name":"string","vram_mib":0}]}}'

Returns the installer's report for a pending, unexpired code. Same session and guessing rules as approve; a wrong code counts as a miss (10 per hour per account and per address).

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Pending pairing. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/pairings/lookup" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_code":"string"}'

The consent step of one-line host onboarding. Applies the same hosting rules as createEnrollmentToken (verified email, host scope, admin block, new-host cap; the first use turns hosting on). go_live (default true) lists the machine's seeded offer, unverified, on its first healthy heartbeat through the same path as listMachine with x-accept-unverified, paid-admission guard included. Audited. Wrong codes are limited as in lookup.

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 200 — Approved. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/pairings/approve" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"user_code":"string","go_live":true}'

pending, expired, approved (once, with a fresh single-use 10-minute enrollment token for POST /api/v1/agents/enroll; the pairing is consumed in the same transaction after the approver's hosting rules are re-checked), then consumed (no token; the enrolled machine's Go-live state). A wrong pairing_id or poll_secret is 404.

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Pairing state. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/pairings/poll" \
  -H "Content-Type: application/json" \
  -d '{"pairing_id":"3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40","poll_secret":"string"}'

Each row carries the machine's hardware specs and its current offer, so a console can render a fleet table without one detail fetch per machine. Specs are read from the same source the public catalog reads (`manifest->devices`). A spec nobody measured is `null` — never 0 and never an empty string; `ram_bytes`, `disk_bytes` and `region` are not measured anywhere today and are therefore null in practice. `current_offer` is null when the machine has no published offer version, which is a real state (a machine mid-onboarding), not a free listing.

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Page of machine summaries. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/hosts/machines" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Includes `telemetry`: the latest agent-reported sample plus `observed_at`, `age_s` and `boot_id`, or null when nothing was ever reported. Telemetry is evidence only and never influences admission, qualification, billing or job state. A measurement the host could not take is ABSENT from the object — it is never rendered as 0 and never carried over from an earlier sample, so a consumer must age it via `age_s` and show `unknown` when stale.

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Machine detail. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/hosts/machines/<id>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Revokes agent credentials and unlists offers. Active rentals or incomplete cleanup return 409. Re-enrollment is required to reconnect.

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 204 — Registration removed; history retained.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X DELETE "https://amplerun.com/api/v1/hosts/machines/<id>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Min/avg/max per measured field per 5-minute bucket, for sparklines. Host owner only: a non-owner receives 404, never 403, so machine existence never leaks. History is retained for 48 h and pruned by the worker cleanup task; a `window` longer than the retention is refused rather than silently clamped. A field that was never measured in a bucket is absent, and a bucket's `samples` count states how much evidence backs it.

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Telemetry history buckets, oldest first. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/hosts/machines/<id>/telemetry" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Aggregate rate, included limits, available_from/available_until, optional maintenance window, expected_version. Versioned future offer only; never alters a running price.

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Offer version committed with new offer_version.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/machines/<id>/offer" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"rate_micro_per_hour":"5000000","included_quotas":{"included_disk_gib":0,"included_egress_gib":0},"available_from":"2026-09-25T12:00:00Z","available_until":"2026-09-25T12:00:00Z","maintenance_windows":[{"starts_at":"2026-09-25T12:00:00Z","ends_at":"2026-09-25T12:00:00Z","reason":"string"}],"expected_version":"1"}'

The host console's listing editor. Despite the verb this is APPEND-ONLY: the next `version` is inserted and no existing row is ever rewritten, so a live job keeps the rate its quote snapshotted — the quote remains the only price authority. `expected_version` is compare-and-swapped against the CURRENT offer version (not the machine version the POST form uses); a race answers 409 with `error.code = VERSION_CONFLICT` and a sibling `current` block so the editor can show what changed instead of overwriting it. `listing_expires_at` has no column of its own and is FOLDED onto `available_until` (the earlier of the two wins — `available_until` already means "bookable until", which is what the catalog filters on); the response echoes the stored value. `min_duration_s` and `max_duration_s` are accepted but NOT stored, because no per-offer duration bound exists in the schema and nothing at quote time would enforce one; they are named back to the caller in `ignored_fields` rather than silently dropped. A publish that would retract availability a live job is already holding is refused 409 CONFLICT.

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Next offer version published. (object)
• 409 — Offer version race (`VERSION_CONFLICT`, with `current`) or a live job whose availability the change would retract (`CONFLICT`). (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X PATCH "https://amplerun.com/api/v1/hosts/machines/<id>/offer" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"expected_version":"1","rate_micro_per_hour":"5000000","included_disk_gib":0,"included_egress_gib":0,"available_from":"2026-09-25T12:00:00Z","available_until":"2026-09-25T12:00:00Z","listing_expires_at":"2026-09-25T12:00:00Z","min_duration_s":0,"max_duration_s":0,"availability_class":"dedicated","preemption_notice_s":0}'

The account-wide `/hosts/earnings` day-series narrowed to one machine and attributed through `jobs.machine_id`, in the identical shape so one chart renders both. Ledger-derived only: every bar links back to `journal_lines` on `host_payable:<id>` for jobs that ran on this machine, and the series reconciles exactly to those rows. `paid_micro` is zero throughout, because payout settlements carry no `job_id` and belong to the account rather than to any one machine — attributing them would double-count a payout across the fleet. A non-owner receives 404, never 403, so machine existence never leaks. A malformed `window` is refused rather than silently defaulted.

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Daily earnings bars for this machine, oldest first. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/hosts/machines/<id>/earnings" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Listing admitted or rejected with findings.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/machines/<id>/list" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 202 — DRAINING.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/machines/<id>/drain" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 202 — UNLISTED.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/machines/<id>/unlist" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

netfacts lane. The agent measures download/upload Mbps and latency from the HOST network namespace against a public endpoint (bounded 30 s) and answers with a machine.nettest receipt that updates the machine's net facts. 202 = queued, never the measurement itself.

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Queued; body carries machine_id, command_id, state=QUEUED.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/machines/<id>/nettest" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Opt-in and eligibility.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/hosts/machines/<id>/idle-pool" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 200 — Current opt-in.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/machines/<id>/idle-pool" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"accept_terms":true,"terms_version":"string"}'

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 200 — Current opt-in.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X DELETE "https://amplerun.com/api/v1/hosts/machines/<id>/idle-pool" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Default false: a machine that never opted in never receives a custom image. Opting in is 409 while the marketplace has custom images disabled; opting out always works and wins any reservation in flight. Custom images still run under the mandatory launch profile. Each change is audited.

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 200 — Current opt-in. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X PUT "https://amplerun.com/api/v1/hosts/machines/<id>/custom-images" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"accept":true}'

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Opt-in, eligibility and credited micro-USDC per machine. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/hosts/idle-pool" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Earnings breakdown. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/hosts/earnings" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Our own marketplace, never a competitor's. Aggregate only: no machine id, host id, offer id or any individual host's rate is ever returned — the only rate values that escape are the p10/median/p90 band of a bucket of at least `min_sample_size` listed machines, plus the CALLER's own median listed rate (`your_rate_micro`). Below the threshold a bucket reports its `sample_size` with every metric null; a median is never computed from a handful of observations. `median_time_to_first_rental_s` has its own sample gate (`rental_sample_size`), because a model can be widely listed and barely rented. Window is half-open UTC `[from, to)`.

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Per-model market aggregates. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/hosts/market" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Amount, asset, state and time. Does not move funds and does not return a payout address. A delegated agent with payouts:read passes the owner id.

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Newest payouts for this host account. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/hosts/payouts" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Payout intent locked against payable, to a saved address, or parked until the emailed link confirms a new one. Sessions confirm with `code` (POST /api/v1/withdrawals/code with kind=payout, or the authenticator); API keys reach saved addresses only.

Auth

Session cookie or API key with the host scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Queued, or waiting for the email link. (TransferAccepted)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/hosts/payouts" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"network":"base","address":"0x1111111111111111111111111111111111111111","amount_micro":"5000000","asset":"USDC","label":"string","code":"string","siwe_message":"string","signature":"string"}'

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Page of ticket summaries. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/tickets" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 201 — Ticket created.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/tickets" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"string","text":"string","job_id":"3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40","payment_reference":"string"}'

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Ticket with messages. Each message carries author (you, support, customer or host, relative to the reader); can_reply is true while the case is open.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/tickets/<id>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

The opener, the rental's host, or an admin (a support reply) may post to an OPEN case; anyone else gets 403 and a closed case 409.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 201 — Message appended.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/tickets/<id>/messages" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"text":"string"}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Filtered operational view. Each row carries account_kind and, for agents, the self-declared agent_profile.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/users" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Everything that decides what this account can do right now, on one response. Credential material is never projected: no password hash, no TOTP secret or backup codes, no API key hash, no session token. A linked sign-in provider shows its name and when it was linked, nothing else. `user.version` is the expected-version token for the actions endpoint.

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — The account's current authority and state.
• 404 — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/users/<id>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

One of five commands. Every one requires an admin session with an enrolled TOTP factor, a fresh `admin-sensitive` step-up grant, an Idempotency-Key, a typed reason and the `expected_version` read from GET /api/v1/admin/users/{id}. A stale version is 409 STALE_VERSION and writes nothing. There is no balance action here and there must never be one. `set_role` and `set_suspension` are refused with 409 CONFLICT when they would leave the system with zero admins; the check locks the admin set inside the transaction, so two demotions racing cannot both succeed. `set_suspension` blocks sign-in and every API key on the next request and stops new admissions for the account, but never cancels a running rental: it keeps metering and billing to funded expiry or stop. `reset_mfa` clears the enrolment and every session so the user must re-enrol; it never reveals or sets a secret.

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Request body (application/json): object | object | object | object

Responses

• 200 — Applied. Returns the new version, what changed and the stated consequence.
• 409 — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/users/<id>/actions" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"action":"set_role","role":"renter","reason":"string","expected_version":"string"}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Filtered operational view.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/machines" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Filtered operational view.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/jobs" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Filtered operational view.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/ledger" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Filtered operational view.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/payouts" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Filtered operational view.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/tickets" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Delegation rows.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/host-delegations" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Filtered operational view.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/audit" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Reconciliation status; stale RPC yields UNAVAILABLE without overwriting prior confirmed figures.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/reconciliation" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Read-only. Adds daily UTC series for the range (signups, active users, rentals, GMV, fees, host earnings, deposits by rail, paid transfers, admitted machines), totals against the previous period, the signup funnel, top renters and hosts with masked emails, and live counts. Series rows and totals also carry `gmv_net_micro` (customer credit debits less refund-reversal credits) and `fees_net_micro` (platform fee credits less debits) over journal kinds charge and refund_reversal, stablecoin assets only, decimal strings in micro-units. `attribution` groups signups, depositors and the first credited stablecoin deposit by ref and by utm_content. Admin accounts and the ATTRIBUTION_EXCLUDE list are left out. Null when the report cannot be read. `paid_time.paid_runtime_ms` sums accepted runtime of finished (CLOSED) and in-flight jobs; admitted capacity stops at `retired_at` for retired machines.

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Analytics.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/analytics" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Read-only. Each source is probed independently; a source that cannot be read reports state "unknown" — never a healthy default and never a stale value presented as fresh. The worker staleness threshold is the same one /api/v1/health/ready applies.

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Four independent health blocks
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/status" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Exact whole-id equality only — no prefix, wildcard or fuzzy match, so the endpoint cannot be walked to enumerate records. Every miss returns one identical NOT_FOUND message regardless of which kind was searched.

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — The resolved kind
• 404 — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/search" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Aggregates over the immutable journal. Money is bigint decimal strings end to end. A group whose inputs are unavailable is null, never zero. Read-only; no per-account detail is projected. hot_float carries the hot payout wallet's balance, what it owes, its cap and what would sweep; networks carries each rail keyed by the reconciliation report's own rail id, which is an EVM chain id or "solana-mainnet", with chain_id null on a rail that is not an EVM chain; hot_wallet_gas is the worker's last gas alert for that wallet, dated, dispatched only while gas runs low; and hot_wallet_gas_reading is its routine native-balance reading on the primary chain, taken on every automatic-payout pass including a pass with an empty queue, as balance_wei (a coin quantity in wei, never summed with a micro-amount) with the read_at it was measured at. Both are null when nothing has been recorded, which a caller renders as unknown, never as an empty wallet. gas_floors carries the empty-queue alert thresholds (eth_wei and sol_lamports; "0" means that alert is off) and solana_hot_gas carries the public Solana watch address with its lamport balance and read_at, null until the worker has recorded one.

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Hot wallet float and gas, per-rail books and holdings, treasury asset, customer/host liabilities, platform fees and refund totals.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/treasury" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

What the platform earns and what accounts deposit. earnings is the platform_fee account over the immutable journal, net of refund reversals, per window (today UTC, 7 days, 30 days, all time) with the amount charged, the amount hosts earned and the rentals billed, plus a per-day series for the last 30 days. deposits is every credited deposit of the EVM, Solana and native-coin rails, dated by the journal transaction that credited it, per window and per rail and asset, plus what is seen or held but not yet credited and the newest deposits with their state and a masked account email. Money is bigint decimal strings end to end; a window with no rows keeps count 0 rather than reporting a zero figure; a group whose inputs are unavailable is null. Read-only.

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Fee windows and daily series, deposit windows, rails, pending transfers and the newest deposits.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/finance" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Filtered operational view.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/incidents" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

The qualification records an admission decision was made on, plus the drift between the running manifest hash and the qualified one. With no qualification record, drifted is null (unknown), never false.

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Machine facts
• 404 — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/machines/<id>/evidence" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

D-19(b)/(c). Admin session; no step-up required. 409 when no qualification_records row binds the template to at least one admitted machine; fixtures never publish.

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Responses

• 202 — Publish accepted; audit event recorded.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/templates/<templateId>/publish" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"string"}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Responses

• 202 — Approved.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/machines/<id>/approve" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"string","expected_version":"1"}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Responses

• 202 — Quarantined.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/machines/<id>/quarantine" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"string","expected_version":"1"}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Responses

• 200 — The same reference was already allocated.
• 201 — Period allocated.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/idle-pool/periods" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"period_start":"2026-09-25T12:00:00Z","period_end":"2026-09-25T12:00:00Z","gross_micro":"5000000","source":"string","reference":"string","commission_bps":0}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Responses

• 202 — Refund adjustment committed once; cumulative cap enforced.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/refunds" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"job_id":"3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40","amount_micro":"5000000","reason":"string","evidence":["string"]}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Responses

• 202 — Approved.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/payouts/<id>/approve" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"manifest_hash":"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","reason":"string"}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Responses

• 202 — Accepted for broadcast. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/payouts/<id>/signed-transaction" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"raw_transaction":"string"}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Responses

• 202 — Decision recorded (audited with the admin and reason). (object)
• 409 — The request is no longer unsigned (a nonce is pinned); it cannot be reviewed.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/payouts/<id>/review" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"decision":"approve","reason":"string"}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Responses

• 202 — Decision recorded (audited with the admin and reason). (object)
• 409 — The request is no longer unsigned (a nonce is pinned); it cannot be reviewed.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/withdrawals/<id>/review" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"decision":"approve","reason":"string"}'

While public admission is paused, only a valid acceptance authorization (see schemas/acceptance-authorization.schema.json) consumed by the shared paid_admission_guard permits funding credit, reservation, host publication, payout and withdrawal.

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Responses

• 202 — Admission state committed.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/admissions" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"reason":"string"}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — Settings grouped by category. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X GET "https://amplerun.com/api/v1/admin/settings" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY"

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

required (UUID header)

Responses

• 200 — Written. The new version. (object)
• 409 — Version conflict — nothing was overwritten. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X PATCH "https://amplerun.com/api/v1/admin/settings/<key>" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"value":"string","reason":"string","expected_version":0}'

Auth

Admin session with enrolled TOTP; API keys are rejected

Idempotency-Key

not used

Responses

• 200 — The real result of the check. (object)
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

curl -X POST "https://amplerun.com/api/v1/admin/settings/test" \
  -H "Authorization: Bearer $AMPLERUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subsystem":"mail","provider":"github"}'

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Process alive. (object)

Example

curl -X GET "https://amplerun.com/api/v1/health/live"

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Ready. (object)
• 503 — Degraded; redacted reasons. (object)

Example

curl -X GET "https://amplerun.com/api/v1/health/ready"

While admissions_paused is true, new reservations are refused with 403 ADMISSION_PAUSED; running rentals are unaffected.

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Status. (object)

Example

curl -X GET "https://amplerun.com/api/v1/status"