REST API reference

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 · Schema definitions · Developer quickstart · Errors

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 before spending.

account

Method	Path	Operation
GET	/api/v1/auth/providers	getSignInProviders
GET	/api/v1/account	getAccount
GET	/api/v1/account/sessions	listSessions
DELETE	/api/v1/account/sessions/{id}	revokeSession
GET	/api/v1/account/api-keys	listApiKeys
POST	/api/v1/account/api-keys	createApiKey
DELETE	/api/v1/account/api-keys/{id}	revokeApiKey
GET	/api/v1/account/integrations/{provider}	getIntegration
POST	/api/v1/account/integrations/{provider}	setIntegration
DELETE	/api/v1/account/integrations/{provider}	removeIntegration
POST	/api/v1/account/export	exportAccount
POST	/api/v1/account/deletion-request	requestAccountDeletion

catalog

Method	Path	Operation
GET	/api/v1/offers	listOffers
GET	/api/v1/offers/{id}	getOffer
GET	/api/v1/templates	listTemplates
GET	/api/v1/templates/{templateId}	getTemplate

jobs

Method	Path	Operation
POST	/api/v1/quotes	createQuote
GET	/api/v1/jobs	listJobs
POST	/api/v1/jobs	createJob
GET	/api/v1/jobs/{id}	getJob
GET	/api/v1/jobs/{id}/events	listJobEvents
GET	/api/v1/jobs/{id}/access	getJobAccess
GET	/api/v1/jobs/{id}/openai/v1/models	relayListModels
POST	/api/v1/jobs/{id}/openai/v1/chat/completions	relayChatCompletions
POST	/api/v1/jobs/{id}/openai/v1/completions	relayCompletions
POST	/api/v1/jobs/{id}/openai/v1/embeddings	relayEmbeddings
POST	/api/v1/jobs/{id}/stop	stopJob
POST	/api/v1/jobs/{id}/budget-extension	extendJobBudget
POST	/api/v1/jobs/{id}/rerun	rerunJob

wallets

Method	Path	Operation
GET	/api/v1/wallets	listWallets
POST	/api/v1/wallets/nonce	createWalletNonce
POST	/api/v1/wallets/link	linkWallet
DELETE	/api/v1/wallets/{binding_id}	unlinkWallet

billing

Method	Path	Operation
POST	/api/v1/funding-intents	createFundingIntent
GET	/api/v1/funding-intents/{id}	getFundingIntent
POST	/api/v1/funding-intents/{id}/claim	claimFundingIntent
GET	/api/v1/billing	getBalances
GET	/api/v1/billing/deposit-address	getDepositAddress
GET	/api/v1/billing/entries	listLedgerEntries
GET	/api/v1/billing/receipts/{job}	getReceipt
POST	/api/v1/billing/x402/top-up	x402TopUp
POST	/api/v1/withdrawals	createWithdrawal
POST	/api/v1/withdrawals/code	sendWithdrawalCode
GET	/api/v1/withdrawal-addresses	listWithdrawalAddresses
POST	/api/v1/withdrawal-addresses	addWithdrawalAddress
DELETE	/api/v1/withdrawal-addresses/{id}	removeWithdrawalAddress
POST	/api/v1/withdrawal-addresses/confirm	confirmWithdrawalAddress

hosts

Method	Path	Operation
POST	/api/v1/hosts/enrollment-tokens	createEnrollmentToken
POST	/api/v1/hosts/pairings	createHostPairing
POST	/api/v1/hosts/pairings/lookup	lookupHostPairing
POST	/api/v1/hosts/pairings/approve	approveHostPairing
POST	/api/v1/hosts/pairings/poll	pollHostPairing
GET	/api/v1/hosts/machines	listMachines
GET	/api/v1/hosts/machines/{id}	getMachine
DELETE	/api/v1/hosts/machines/{id}	removeMachine
GET	/api/v1/hosts/machines/{id}/telemetry	getMachineTelemetry
POST	/api/v1/hosts/machines/{id}/offer	publishOffer
PATCH	/api/v1/hosts/machines/{id}/offer	editOffer
GET	/api/v1/hosts/machines/{id}/earnings	getMachineEarnings
POST	/api/v1/hosts/machines/{id}/list	listMachineForRent
POST	/api/v1/hosts/machines/{id}/drain	drainMachine
POST	/api/v1/hosts/machines/{id}/unlist	unlistMachine
POST	/api/v1/hosts/machines/{id}/nettest	queueMachineNettest
PUT	/api/v1/hosts/machines/{id}/custom-images	setMachineCustomImages
GET	/api/v1/hosts/earnings	getHostEarnings
GET	/api/v1/hosts/market	getHostMarket
POST	/api/v1/hosts/payouts	requestPayout

agents

Method	Path	Operation
POST	/api/v1/agents/accounts/challenge	createAgentAccountChallenge
POST	/api/v1/agents/accounts	registerAgentAccount

support

Method	Path	Operation
GET	/api/v1/tickets	listTickets
POST	/api/v1/tickets	createTicket
GET	/api/v1/tickets/{id}	getTicket
POST	/api/v1/tickets/{id}/messages	addTicketMessage

admin

Method	Path	Operation
GET	/api/v1/admin/users	adminListUsers
GET	/api/v1/admin/users/{id}	adminGetUser
POST	/api/v1/admin/users/{id}/actions	adminUserAction
GET	/api/v1/admin/machines	adminListMachines
GET	/api/v1/admin/jobs	adminListJobs
GET	/api/v1/admin/ledger	adminListLedger
GET	/api/v1/admin/payouts	adminListPayouts
GET	/api/v1/admin/tickets	adminListTickets
GET	/api/v1/admin/audit	adminListAudit
GET	/api/v1/admin/reconciliation	adminGetReconciliation
GET	/api/v1/admin/analytics	adminGetAnalytics
GET	/api/v1/admin/status	adminGetStatus
GET	/api/v1/admin/search	adminSearch
GET	/api/v1/admin/treasury	adminGetTreasury
GET	/api/v1/admin/incidents	adminListIncidents
GET	/api/v1/admin/machines/{id}/evidence	adminGetMachineEvidence
POST	/api/v1/admin/templates/{templateId}/publish	adminPublishTemplate
POST	/api/v1/admin/machines/{id}/approve	adminApproveMachine
POST	/api/v1/admin/machines/{id}/quarantine	adminQuarantineMachine
POST	/api/v1/admin/refunds	adminCreateRefund
POST	/api/v1/admin/payouts/{id}/approve	adminApprovePayout
POST	/api/v1/admin/payouts/{id}/signed-transaction	adminSubmitSignedTransaction
POST	/api/v1/admin/payouts/{id}/review	adminReviewPayout
POST	/api/v1/admin/withdrawals/{id}/review	adminReviewWithdrawal
POST	/api/v1/admin/admissions	adminSetAdmissions
GET	/api/v1/admin/settings	adminListSettings
PATCH	/api/v1/admin/settings/{key}	adminUpdateSetting
POST	/api/v1/admin/settings/test	adminTestSetting

health

Method	Path	Operation
GET	/api/v1/health/live	getLiveness
GET	/api/v1/health/ready	getReadiness
GET	/api/v1/status	getStatus