API reference

GET /api/v1/offers

List admitted offers (public)

Filter by model, minimum VRAM, GPU count, total machine price, region, RAM/disk, measured bandwidth and template compatibility. Only available, recently healthy admitted offers can reserve. No cached public responses. With template_id (D-19(c)) every item carries a server-computed fit object.

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, 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

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

GET /api/v1/offers/{id}

Get one offer (public)

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, 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

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

GET /api/v1/templates

List published templates (public)

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, 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

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

GET /api/v1/templates/{templateId}

Get one published template (public)

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, 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

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

POST /api/v1/quotes

Create immutable quote (verified renter)

Returns an immutable quote with 60s expiry, terms version, machine manifest hash and total rate. Refresh stale catalog quotes before charging.

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, 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":"00000000-0000-4000-8000-000000000000","image_digest":"string","duration_limit_s":1,"budget_micro":"string","template_id":"00000000-0000-4000-8000-000000000000"}'

GET /api/v1/jobs

List own jobs (renter owner/admin)

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, 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"

POST /api/v1/jobs

Reserve job from quote (quote owner)

Atomically holds budget, reserves machine, increments fence and queues start. Rejects expired quote, changed manifest, unavailable machine or insufficient spendable funds without partial holds.

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, 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":"00000000-0000-4000-8000-000000000000","ssh_public_key":"string"}'

GET /api/v1/jobs/{id}

Job status, cumulative charge, funded-through (owner/admin)

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, 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"

GET /api/v1/jobs/{id}/events

Sequenced job events (owner/admin); logs sanitized and bounded

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, 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"

GET /api/v1/jobs/{id}/access

Current endpoint, SSH host-key fingerprint and command (renter owner)

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, 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"

POST /api/v1/jobs/{id}/stop

Stop job (renter owner/admin); repeat is idempotent

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, 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":"string"}'

POST /api/v1/jobs/{id}/budget-extension

Append funded budget amendment (renter owner)

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, 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":"string","new_duration_limit_s":1,"expected_job_version":"string","expected_budget_version":"string"}'

POST /api/v1/jobs/{id}/rerun

Fresh quote parameters (renter owner); never launches/spends automatically

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, 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)"

GET /api/v1/account

Profile/security metadata (self); no password/token hashes

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Account profile.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 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"

GET /api/v1/account/sessions

Session metadata (self)

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, 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"

DELETE /api/v1/account/sessions/{id}

Revoke one of the caller's own sessions (self; interactive sessions only)

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, 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"

GET /api/v1/account/api-keys

List API keys (self)

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — API key metadata; secrets never re-shown.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 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"

POST /api/v1/account/api-keys

Create API key (self, step-up)

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.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 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-01-01T00:00:00Z","scopes":["renter"]}'

DELETE /api/v1/account/api-keys/{id}

Revoke API key (self, step-up)

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, 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)"

POST /api/v1/account/export

Data export (self, recent re-auth)

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, 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)"

POST /api/v1/account/deletion-request

Retention-aware deletion request (self, recent re-auth); required ledger evidence preserved under disclosed policy

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, 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)"

GET /api/v1/wallets

List wallet bindings (verified self)

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, 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"

POST /api/v1/wallets/nonce

SIWE nonce (verified self, re-auth)

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, 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)"

POST /api/v1/wallets/link

Link wallet via SIWE proof (verified self, re-auth)

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, 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":"string","siwe_message":"string","signature":"string"}'

DELETE /api/v1/wallets/{binding_id}

Unlink wallet (verified self, re-auth)

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, 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)"

POST /api/v1/wallets/{binding_id}/payout-destination

Select proved, versioned payout destination (verified self, recent re-auth/SIWE)

Future transfer intents bind wallet_binding_id,address,version; pending intents never retarget.

Auth

Session cookie or API key with the renter scope

Idempotency-Key

required (UUID header)

Responses

• 202 — Destination version selected.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 503 unavailable money/provider state with retryable:true. (ErrorEnvelope)

Example

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

POST /api/v1/funding-intents

Create funding intent (bound wallet owner)

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, 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":"00000000-0000-4000-8000-000000000000","amount_micro":"string"}'

POST /api/v1/funding-intents/{id}/claim

Claim funding intent (intent owner)

Verifies ERC20 Transfer sender=bound wallet, recipient=treasury, exact token/chain, successful receipt, canonical block and finalized head; PENDING/CONFIRMED/EXCEPTION. 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, 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}'

GET /api/v1/billing

Balance summary (self/admin); spendable/held/pending/disputed/withdrawable separately

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, 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"

GET /api/v1/billing/entries

Itemized ledger entries (self/admin)

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, 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"

GET /api/v1/billing/receipts/{job}

Itemized invoice/receipt and supplier information for a job (self/admin)

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Receipt.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 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"

POST /api/v1/withdrawals

Create withdrawal (self, step-up)

Locked withdrawal intent; raw/unproved destination rejected; no spendable credit while transfer pending.

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

• 202 — Withdrawal intent locked.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 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 '{"amount_micro":"string","wallet_binding_id":"00000000-0000-4000-8000-000000000000","destination_version":"string"}'

POST /api/v1/hosts/enrollment-tokens

Host enrollment token (verified host account)

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, 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)"

GET /api/v1/hosts/machines

List own machines (host owner/admin)

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Page of machine summaries.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 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"

GET /api/v1/hosts/machines/{id}

Machine detail: compatibility findings, current offer/job, observed metrics, drain state (host owner/admin)

Auth

Session cookie or API key with the host scope

Idempotency-Key

not used

Responses

• 200 — Machine detail.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 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"

POST /api/v1/hosts/machines/{id}/offer

Publish versioned future offer (host owner)

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, 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":"string","included_quotas":{"included_disk_gib":0,"included_egress_gib":0},"available_from":"2026-01-01T00:00:00Z","available_until":"2026-01-01T00:00:00Z","maintenance_windows":[{"starts_at":"2026-01-01T00:00:00Z","ends_at":"2026-01-01T00:00:00Z","reason":"string"}],"expected_version":"string"}'

POST /api/v1/hosts/machines/{id}/list

List machine (host owner); admission checks apply

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, 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)"

POST /api/v1/hosts/machines/{id}/drain

Drain machine (host owner); stops new bookings, never kills an active job or retrieval cleanup

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, 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)"

POST /api/v1/hosts/machines/{id}/unlist

Unlist idle offer (host owner); never kills an active job or retrieval cleanup

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, 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)"

GET /api/v1/hosts/earnings

Earnings (host owner): earned, disputed, payable, requested, settled; gross vs 10% fee; no utilization guess

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, 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"

POST /api/v1/hosts/payouts

Request payout (host owner, step-up)

Payout intent locked against payable; raw/unproved destination rejected.

Auth

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

Idempotency-Key

required (UUID header)

Responses

• 202 — Payout intent locked.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 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 '{"amount_micro":"string","wallet_binding_id":"00000000-0000-4000-8000-000000000000","destination_version":"string"}'

GET /api/v1/tickets

List own tickets (opener); cursor paged, ordered by id

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, 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"

POST /api/v1/tickets

Open support ticket (participant/admin); secrets redacted, ownership checked

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, 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":"00000000-0000-4000-8000-000000000000","payment_reference":"string"}'

GET /api/v1/tickets/{id}

Ticket thread (participant/admin); participants see only their own permitted thread

Auth

Session cookie or API key with the renter scope

Idempotency-Key

not used

Responses

• 200 — Ticket with messages.
• default — Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 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"

POST /api/v1/tickets/{id}/messages

Append message (participant/admin)

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, 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"}'

GET /api/v1/admin/users

Admin user view (Admin+MFA); immutable references

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, 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"

GET /api/v1/admin/machines

Admin machine view (Admin+MFA)

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, 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"

GET /api/v1/admin/jobs

Admin job view (Admin+MFA)

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, 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"

GET /api/v1/admin/ledger

Admin ledger view (Admin+MFA)

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, 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"

GET /api/v1/admin/payouts

Admin payout view (Admin+MFA)

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, 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"

GET /api/v1/admin/tickets

Admin ticket view (Admin+MFA)

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, 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"

GET /api/v1/admin/audit

Admin audit view (Admin+MFA)

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, 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"

GET /api/v1/admin/reconciliation

Admin reconciliation view (Admin+MFA); unexplained differences >0 micro pause new paid admissions/payouts

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, 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"

GET /api/v1/admin/analytics

Admin analytics (Admin+MFA); committed capacity, paid time, GMV, fees, costs, refunds and repeat users separated; unavailable inputs stay null

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, 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"

POST /api/v1/admin/templates/{templateId}/publish

Publish template (Admin+MFA); audit event; refused unless a qualification record binds it to an admitted machine

D-19(b)/(c). Requires MFA step-up. 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, 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"}'

POST /api/v1/admin/machines/{id}/approve

Approve machine (Admin+MFA); reason + expected version; in-flight work gets explicit policy, not silent deletion

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, 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":"string"}'

POST /api/v1/admin/machines/{id}/quarantine

Quarantine machine (Admin+MFA); reason + expected version; in-flight work gets explicit policy, not silent deletion

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, 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":"string"}'

POST /api/v1/admin/refunds

Refund (Admin+recentMFA); evidence/reason, exact immutable manifest or compensating journal; no raw balance-edit endpoint

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, 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":"00000000-0000-4000-8000-000000000000","amount_micro":"string","reason":"string","evidence":["string"]}'

POST /api/v1/admin/payouts/{id}/approve

Approve payout manifest (Admin+recentMFA); exact immutable manifest hash; destination change invalidates approval

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, 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":"string","reason":"string"}'

POST /api/v1/admin/payouts/{id}/signed-transaction

Submit signer-produced raw transaction (Admin+recentMFA); verified to match approved manifest and signer; returns deterministic hash

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, 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"}'

POST /api/v1/admin/admissions

Pause/resume admissions (Admin+recentMFA); pauses new jobs/credits as appropriate, never abrupt tenant termination

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, 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"}'

GET /api/v1/health/live

Liveness (public minimal)

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Process alive.

Example

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

GET /api/v1/health/ready

Readiness (public minimal); schema/DB/worker/clock with redacted degraded reasons; no internal topology leakage

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Ready.
• 503 — Degraded; redacted reasons.

Example

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

GET /api/v1/status

Public status (minimal)

Auth

Public — no credential

Idempotency-Key

not used

Responses

• 200 — Status.

Example

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