# REST API reference

Contract-derived endpoints, parameters, bodies, schemas and responses.

This reference is generated from AmpleRun contract v3. It does not make API requests or collect credentials.

Machine API origin: `https://amplerun-api.spiry.org`. The documentation hostname is not an API server.

[Download OpenAPI 3.1](/openapi.json) · [Schema definitions](https://docs.amplerun.com/reference/schemas.md) · [Developer quickstart](https://docs.amplerun.com/start/developer.md) · [Errors](https://docs.amplerun.com/reference/errors.md)

## Authentication and money

Programs send a scoped `ark_...` key as `Authorization: Bearer`. Renter scope authorizes rentals; host scope authorizes host operations. Administrative operations require an interactive admin session and their stated step-up proofs, not an API key. Host-agent endpoints have their own signed identity. Wallet registration uses a signed challenge, not an existing key.

Money is expressed as integer micro-unit strings. Read the budget and asset in every quote. Quotes are free and do not reserve a machine; a repeated quote request can return a fresh quote. Retrying a reservation uses the same logical idempotency key. Read [catalog and quotes](https://docs.amplerun.com/renting/catalog-and-quotes.md) before spending.

## account

| Method | Path | Operation |
| --- | --- | --- |
| GET | [`/api/v1/auth/providers`](https://docs.amplerun.com/reference/api/get-sign-in-providers.md) | `getSignInProviders` |
| GET | [`/api/v1/account`](https://docs.amplerun.com/reference/api/get-account.md) | `getAccount` |
| GET | [`/api/v1/account/sessions`](https://docs.amplerun.com/reference/api/list-sessions.md) | `listSessions` |
| DELETE | [`/api/v1/account/sessions/{id}`](https://docs.amplerun.com/reference/api/revoke-session.md) | `revokeSession` |
| GET | [`/api/v1/account/api-keys`](https://docs.amplerun.com/reference/api/list-api-keys.md) | `listApiKeys` |
| POST | [`/api/v1/account/api-keys`](https://docs.amplerun.com/reference/api/create-api-key.md) | `createApiKey` |
| DELETE | [`/api/v1/account/api-keys/{id}`](https://docs.amplerun.com/reference/api/revoke-api-key.md) | `revokeApiKey` |
| GET | [`/api/v1/account/integrations/{provider}`](https://docs.amplerun.com/reference/api/get-integration.md) | `getIntegration` |
| POST | [`/api/v1/account/integrations/{provider}`](https://docs.amplerun.com/reference/api/set-integration.md) | `setIntegration` |
| DELETE | [`/api/v1/account/integrations/{provider}`](https://docs.amplerun.com/reference/api/remove-integration.md) | `removeIntegration` |
| POST | [`/api/v1/account/export`](https://docs.amplerun.com/reference/api/export-account.md) | `exportAccount` |
| POST | [`/api/v1/account/deletion-request`](https://docs.amplerun.com/reference/api/request-account-deletion.md) | `requestAccountDeletion` |

## catalog

| Method | Path | Operation |
| --- | --- | --- |
| GET | [`/api/v1/offers`](https://docs.amplerun.com/reference/api/list-offers.md) | `listOffers` |
| GET | [`/api/v1/offers/{id}`](https://docs.amplerun.com/reference/api/get-offer.md) | `getOffer` |
| GET | [`/api/v1/templates`](https://docs.amplerun.com/reference/api/list-templates.md) | `listTemplates` |
| GET | [`/api/v1/templates/{templateId}`](https://docs.amplerun.com/reference/api/get-template.md) | `getTemplate` |

## jobs

| Method | Path | Operation |
| --- | --- | --- |
| POST | [`/api/v1/quotes`](https://docs.amplerun.com/reference/api/create-quote.md) | `createQuote` |
| GET | [`/api/v1/jobs`](https://docs.amplerun.com/reference/api/list-jobs.md) | `listJobs` |
| POST | [`/api/v1/jobs`](https://docs.amplerun.com/reference/api/create-job.md) | `createJob` |
| GET | [`/api/v1/jobs/{id}`](https://docs.amplerun.com/reference/api/get-job.md) | `getJob` |
| GET | [`/api/v1/jobs/{id}/events`](https://docs.amplerun.com/reference/api/list-job-events.md) | `listJobEvents` |
| GET | [`/api/v1/jobs/{id}/access`](https://docs.amplerun.com/reference/api/get-job-access.md) | `getJobAccess` |
| GET | [`/api/v1/jobs/{id}/openai/v1/models`](https://docs.amplerun.com/reference/api/relay-list-models.md) | `relayListModels` |
| POST | [`/api/v1/jobs/{id}/openai/v1/chat/completions`](https://docs.amplerun.com/reference/api/relay-chat-completions.md) | `relayChatCompletions` |
| POST | [`/api/v1/jobs/{id}/openai/v1/completions`](https://docs.amplerun.com/reference/api/relay-completions.md) | `relayCompletions` |
| POST | [`/api/v1/jobs/{id}/openai/v1/embeddings`](https://docs.amplerun.com/reference/api/relay-embeddings.md) | `relayEmbeddings` |
| POST | [`/api/v1/jobs/{id}/stop`](https://docs.amplerun.com/reference/api/stop-job.md) | `stopJob` |
| POST | [`/api/v1/jobs/{id}/budget-extension`](https://docs.amplerun.com/reference/api/extend-job-budget.md) | `extendJobBudget` |
| POST | [`/api/v1/jobs/{id}/rerun`](https://docs.amplerun.com/reference/api/rerun-job.md) | `rerunJob` |

## wallets

| Method | Path | Operation |
| --- | --- | --- |
| GET | [`/api/v1/wallets`](https://docs.amplerun.com/reference/api/list-wallets.md) | `listWallets` |
| POST | [`/api/v1/wallets/nonce`](https://docs.amplerun.com/reference/api/create-wallet-nonce.md) | `createWalletNonce` |
| POST | [`/api/v1/wallets/link`](https://docs.amplerun.com/reference/api/link-wallet.md) | `linkWallet` |
| DELETE | [`/api/v1/wallets/{binding_id}`](https://docs.amplerun.com/reference/api/unlink-wallet.md) | `unlinkWallet` |

## billing

| Method | Path | Operation |
| --- | --- | --- |
| POST | [`/api/v1/funding-intents`](https://docs.amplerun.com/reference/api/create-funding-intent.md) | `createFundingIntent` |
| GET | [`/api/v1/funding-intents/{id}`](https://docs.amplerun.com/reference/api/get-funding-intent.md) | `getFundingIntent` |
| POST | [`/api/v1/funding-intents/{id}/claim`](https://docs.amplerun.com/reference/api/claim-funding-intent.md) | `claimFundingIntent` |
| GET | [`/api/v1/billing`](https://docs.amplerun.com/reference/api/get-balances.md) | `getBalances` |
| GET | [`/api/v1/billing/deposit-address`](https://docs.amplerun.com/reference/api/get-deposit-address.md) | `getDepositAddress` |
| GET | [`/api/v1/billing/entries`](https://docs.amplerun.com/reference/api/list-ledger-entries.md) | `listLedgerEntries` |
| GET | [`/api/v1/billing/receipts/{job}`](https://docs.amplerun.com/reference/api/get-receipt.md) | `getReceipt` |
| POST | [`/api/v1/billing/x402/top-up`](https://docs.amplerun.com/reference/api/x402-top-up.md) | `x402TopUp` |
| POST | [`/api/v1/withdrawals`](https://docs.amplerun.com/reference/api/create-withdrawal.md) | `createWithdrawal` |
| POST | [`/api/v1/withdrawals/code`](https://docs.amplerun.com/reference/api/send-withdrawal-code.md) | `sendWithdrawalCode` |
| GET | [`/api/v1/withdrawal-addresses`](https://docs.amplerun.com/reference/api/list-withdrawal-addresses.md) | `listWithdrawalAddresses` |
| POST | [`/api/v1/withdrawal-addresses`](https://docs.amplerun.com/reference/api/add-withdrawal-address.md) | `addWithdrawalAddress` |
| DELETE | [`/api/v1/withdrawal-addresses/{id}`](https://docs.amplerun.com/reference/api/remove-withdrawal-address.md) | `removeWithdrawalAddress` |
| POST | [`/api/v1/withdrawal-addresses/confirm`](https://docs.amplerun.com/reference/api/confirm-withdrawal-address.md) | `confirmWithdrawalAddress` |

## hosts

| Method | Path | Operation |
| --- | --- | --- |
| POST | [`/api/v1/hosts/enrollment-tokens`](https://docs.amplerun.com/reference/api/create-enrollment-token.md) | `createEnrollmentToken` |
| POST | [`/api/v1/hosts/pairings`](https://docs.amplerun.com/reference/api/create-host-pairing.md) | `createHostPairing` |
| POST | [`/api/v1/hosts/pairings/lookup`](https://docs.amplerun.com/reference/api/lookup-host-pairing.md) | `lookupHostPairing` |
| POST | [`/api/v1/hosts/pairings/approve`](https://docs.amplerun.com/reference/api/approve-host-pairing.md) | `approveHostPairing` |
| POST | [`/api/v1/hosts/pairings/poll`](https://docs.amplerun.com/reference/api/poll-host-pairing.md) | `pollHostPairing` |
| GET | [`/api/v1/hosts/machines`](https://docs.amplerun.com/reference/api/list-machines.md) | `listMachines` |
| GET | [`/api/v1/hosts/machines/{id}`](https://docs.amplerun.com/reference/api/get-machine.md) | `getMachine` |
| DELETE | [`/api/v1/hosts/machines/{id}`](https://docs.amplerun.com/reference/api/remove-machine.md) | `removeMachine` |
| GET | [`/api/v1/hosts/machines/{id}/telemetry`](https://docs.amplerun.com/reference/api/get-machine-telemetry.md) | `getMachineTelemetry` |
| POST | [`/api/v1/hosts/machines/{id}/offer`](https://docs.amplerun.com/reference/api/publish-offer.md) | `publishOffer` |
| PATCH | [`/api/v1/hosts/machines/{id}/offer`](https://docs.amplerun.com/reference/api/edit-offer.md) | `editOffer` |
| GET | [`/api/v1/hosts/machines/{id}/earnings`](https://docs.amplerun.com/reference/api/get-machine-earnings.md) | `getMachineEarnings` |
| POST | [`/api/v1/hosts/machines/{id}/list`](https://docs.amplerun.com/reference/api/list-machine-for-rent.md) | `listMachineForRent` |
| POST | [`/api/v1/hosts/machines/{id}/drain`](https://docs.amplerun.com/reference/api/drain-machine.md) | `drainMachine` |
| POST | [`/api/v1/hosts/machines/{id}/unlist`](https://docs.amplerun.com/reference/api/unlist-machine.md) | `unlistMachine` |
| POST | [`/api/v1/hosts/machines/{id}/nettest`](https://docs.amplerun.com/reference/api/queue-machine-nettest.md) | `queueMachineNettest` |
| PUT | [`/api/v1/hosts/machines/{id}/custom-images`](https://docs.amplerun.com/reference/api/set-machine-custom-images.md) | `setMachineCustomImages` |
| GET | [`/api/v1/hosts/earnings`](https://docs.amplerun.com/reference/api/get-host-earnings.md) | `getHostEarnings` |
| GET | [`/api/v1/hosts/market`](https://docs.amplerun.com/reference/api/get-host-market.md) | `getHostMarket` |
| POST | [`/api/v1/hosts/payouts`](https://docs.amplerun.com/reference/api/request-payout.md) | `requestPayout` |

## agents

| Method | Path | Operation |
| --- | --- | --- |
| POST | [`/api/v1/agents/accounts/challenge`](https://docs.amplerun.com/reference/api/create-agent-account-challenge.md) | `createAgentAccountChallenge` |
| POST | [`/api/v1/agents/accounts`](https://docs.amplerun.com/reference/api/register-agent-account.md) | `registerAgentAccount` |

## support

| Method | Path | Operation |
| --- | --- | --- |
| GET | [`/api/v1/tickets`](https://docs.amplerun.com/reference/api/list-tickets.md) | `listTickets` |
| POST | [`/api/v1/tickets`](https://docs.amplerun.com/reference/api/create-ticket.md) | `createTicket` |
| GET | [`/api/v1/tickets/{id}`](https://docs.amplerun.com/reference/api/get-ticket.md) | `getTicket` |
| POST | [`/api/v1/tickets/{id}/messages`](https://docs.amplerun.com/reference/api/add-ticket-message.md) | `addTicketMessage` |

## admin

| Method | Path | Operation |
| --- | --- | --- |
| GET | [`/api/v1/admin/users`](https://docs.amplerun.com/reference/api/admin-list-users.md) | `adminListUsers` |
| GET | [`/api/v1/admin/users/{id}`](https://docs.amplerun.com/reference/api/admin-get-user.md) | `adminGetUser` |
| POST | [`/api/v1/admin/users/{id}/actions`](https://docs.amplerun.com/reference/api/admin-user-action.md) | `adminUserAction` |
| GET | [`/api/v1/admin/machines`](https://docs.amplerun.com/reference/api/admin-list-machines.md) | `adminListMachines` |
| GET | [`/api/v1/admin/jobs`](https://docs.amplerun.com/reference/api/admin-list-jobs.md) | `adminListJobs` |
| GET | [`/api/v1/admin/ledger`](https://docs.amplerun.com/reference/api/admin-list-ledger.md) | `adminListLedger` |
| GET | [`/api/v1/admin/payouts`](https://docs.amplerun.com/reference/api/admin-list-payouts.md) | `adminListPayouts` |
| GET | [`/api/v1/admin/tickets`](https://docs.amplerun.com/reference/api/admin-list-tickets.md) | `adminListTickets` |
| GET | [`/api/v1/admin/audit`](https://docs.amplerun.com/reference/api/admin-list-audit.md) | `adminListAudit` |
| GET | [`/api/v1/admin/reconciliation`](https://docs.amplerun.com/reference/api/admin-get-reconciliation.md) | `adminGetReconciliation` |
| GET | [`/api/v1/admin/analytics`](https://docs.amplerun.com/reference/api/admin-get-analytics.md) | `adminGetAnalytics` |
| GET | [`/api/v1/admin/status`](https://docs.amplerun.com/reference/api/admin-get-status.md) | `adminGetStatus` |
| GET | [`/api/v1/admin/search`](https://docs.amplerun.com/reference/api/admin-search.md) | `adminSearch` |
| GET | [`/api/v1/admin/treasury`](https://docs.amplerun.com/reference/api/admin-get-treasury.md) | `adminGetTreasury` |
| GET | [`/api/v1/admin/incidents`](https://docs.amplerun.com/reference/api/admin-list-incidents.md) | `adminListIncidents` |
| GET | [`/api/v1/admin/machines/{id}/evidence`](https://docs.amplerun.com/reference/api/admin-get-machine-evidence.md) | `adminGetMachineEvidence` |
| POST | [`/api/v1/admin/templates/{templateId}/publish`](https://docs.amplerun.com/reference/api/admin-publish-template.md) | `adminPublishTemplate` |
| POST | [`/api/v1/admin/machines/{id}/approve`](https://docs.amplerun.com/reference/api/admin-approve-machine.md) | `adminApproveMachine` |
| POST | [`/api/v1/admin/machines/{id}/quarantine`](https://docs.amplerun.com/reference/api/admin-quarantine-machine.md) | `adminQuarantineMachine` |
| POST | [`/api/v1/admin/refunds`](https://docs.amplerun.com/reference/api/admin-create-refund.md) | `adminCreateRefund` |
| POST | [`/api/v1/admin/payouts/{id}/approve`](https://docs.amplerun.com/reference/api/admin-approve-payout.md) | `adminApprovePayout` |
| POST | [`/api/v1/admin/payouts/{id}/signed-transaction`](https://docs.amplerun.com/reference/api/admin-submit-signed-transaction.md) | `adminSubmitSignedTransaction` |
| POST | [`/api/v1/admin/payouts/{id}/review`](https://docs.amplerun.com/reference/api/admin-review-payout.md) | `adminReviewPayout` |
| POST | [`/api/v1/admin/withdrawals/{id}/review`](https://docs.amplerun.com/reference/api/admin-review-withdrawal.md) | `adminReviewWithdrawal` |
| POST | [`/api/v1/admin/admissions`](https://docs.amplerun.com/reference/api/admin-set-admissions.md) | `adminSetAdmissions` |
| GET | [`/api/v1/admin/settings`](https://docs.amplerun.com/reference/api/admin-list-settings.md) | `adminListSettings` |
| PATCH | [`/api/v1/admin/settings/{key}`](https://docs.amplerun.com/reference/api/admin-update-setting.md) | `adminUpdateSetting` |
| POST | [`/api/v1/admin/settings/test`](https://docs.amplerun.com/reference/api/admin-test-setting.md) | `adminTestSetting` |

## health

| Method | Path | Operation |
| --- | --- | --- |
| GET | [`/api/v1/health/live`](https://docs.amplerun.com/reference/api/get-liveness.md) | `getLiveness` |
| GET | [`/api/v1/health/ready`](https://docs.amplerun.com/reference/api/get-readiness.md) | `getReadiness` |
| GET | [`/api/v1/status`](https://docs.amplerun.com/reference/api/get-status.md) | `getStatus` |

---
Generated from the AmpleRun API contract.
Canonical: https://docs.amplerun.com/reference/api/