Aquanode Orchestrator API
API documentation for the Aquanode deployment orchestrator.
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
API documentation for the Aquanode deployment orchestrator.
Endpoints 84
Connector
- POSTRegister a connector session
/connector/sessionsCalled by aq connect with an API key (deploy scope) and x-team-id. Returns a session token (aq_cs_..., stored hashed, 24 h) that authenticates the long-poll,… - GETLong-poll for relayed requests
/connector/sessions/:id/requestsSession token auth. Atomically claims (FOR UPDATE SKIP LOCKED) the oldest queued request for the session team whose provider the session holds a key for, and… - POSTHeartbeat a running relayed request
/connector/requests/:id/heartbeatEvery heartbeatSeconds. A running request with no heartbeat for 3 intervals is stale: the orchestrator treats it as UNKNOWN, never as failed. 409 means the… - POSTPost the result of a relayed request
/connector/requests/:id/resultThe HTTP status and JSON body the local handler produced, or { status: 0, error } when the executor could not run it. A result that arrives after the deadline… - DELETEEnd a connector session
/connector/sessions/:id - GETConnector status for the team
/connector/statusOnline sessions (seen within 60 s) and verifiedProviders: the providers that are both online and in the server-side verified list, i.e. the only ones a… - GETProviders on the multi-cloud console
/connector/providersEach provider the local executor accepts credentials for, with the fields the console asks for. Mirrors the allowlist in mjolnir local; aws is excluded.
Deployments
- GETList deployments
/deploymentsRetrieves all deployments for the current team, with optional filtering. - GETGet deployment details
/deployments/:deploymentIdRetrieves detailed information about a specific deployment. - POSTCreate deployment
/deployments/deployTriggers the creation of a new deployment based on the provided configuration. - POSTRent the cheapest matching GPU
/deployments/upRents the cheapest GPU matching the optional filters and brings up a box, with an optional template, in one call. Bills the team. Needs an API key with the… - GETGet deployment status
/deployments/:deploymentId/statusStatus of a deployment with its job information and, for a live VM, the on-box agent status. - POSTClose deployment
/deployments/closeCloses an active deployment. - GETGet deployment analytics
/deployments/analyticsRetrieves analytics and usage data for all team deployments.
Credits
- GETGet team credits
/creditsRetrieves the total available credits for the current team, and the team's prepaid plan (with source polar or comp; null when it has none, { status: 'unknown'… - GETGet detailed credit info
/credits/detailsRetrieves comprehensive credit usage statistics and transaction history. - POSTStart a prepaid plan checkout
/credits/plans/checkoutCreates a Polar checkout for a monthly plan and returns its URL. Each paid period grants GPU credit at face value into the team wallet; unused plan credit… - GETOpen the plan customer portal
/credits/plans/portalReturns a Polar customer-portal URL where the customer cancels the plan or changes the card on file. Requires the full API key scope when called with an API…
Marketplace
- GETGet marketplace data
/marketplaceRetrieves current marketplace data including available providers and GPU pricing. - GETGet cached marketplace data
/marketplace/cachedRetrieves cached marketplace data for faster response times. - GETGet GPU breakdown
/marketplace/breakdownRetrieves detailed breakdown of GPU availability and pricing. - GETGet marketplace provider read status
/marketplace/provider-statusRetrieves structured per-provider read status for the current marketplace fetch cycle: read-OK (offer count may legitimately be 0), read-FAILED, or read-STALE… - GETGet user quick picks
/marketplace/quick-picksRetrieves personalized quick pick deployment options for the current user.
User Settings
- GETGet user settings
/settingsRetrieves the current user's profile and settings. - POSTUpsert user settings
/settingsCreates or updates user settings. - PATCHUpdate user settings
/settingsPartially updates user settings. - GETList SSH keys
/settings/ssh-keysRetrieves the current user's SSH keys. When the request carries an x-team-id header for a team the caller belongs to, keys other members have shared with that… - POSTAdd SSH key
/settings/ssh-keysAdds a new SSH public key to the user's account. - DELETEDelete SSH key
/settings/ssh-keys/:keyIdRemoves an SSH key from the user's account. - PATCHUpdate SSH key
/settings/ssh-keys/:keyIdUpdates an existing SSH key. - PATCHShare or unshare an SSH key with your team
/settings/ssh-keys/:keyId/shareShares one of your OWN keys with the team named by the x-team-id header, so any member of that team can select it when deploying, or withdraws that sharing.… - GETList user connections
/settings/connectionsRetrieves all external account connections (e.g., GitHub, Google). - POSTCreate user connection
/settings/connectionsConnects an external account. - GETList integration configs
/settings/integration-configsRetrieves storage configurations (S3, Lighthouse, etc.). - POSTCreate integration config
/settings/integration-configsAdds a new storage integration configuration. - GETResolve Aquanode managed storage
/settings/integration-configs/managed-storageReturns a per-tenant scoped Backblaze B2 application key (never master creds) plus STORAGE_PREFIX=<teamId> for a logged-in CLI (ogre --to aquanode, #178/CD2)… - GETList preset scripts
/settings/preset-scriptsRetrieves custom scripts defined by the user. - POSTCreate preset script
/settings/preset-scriptsAdds a new preset script.
Snapshots
- GETGet snapshot supported deployments
/snapshots/deploymentsLists all deployments that support snapshotting. - GETGet user snapshot history
/snapshots/historyRetrieves the complete snapshot history for the current user. - POSTRegister an external/CLI snapshot
/snapshots/externalRegisters a snapshot created by a standalone ogre/aq CLI run that has no Aquanode deployment, recording it as an account-owned, deployment-less backup so it… - POSTCreate snapshot
/snapshots/:deploymentId/createTriggers the creation of a new snapshot for a specific deployment. - POSTCreate a link-scoped snapshot share
/snapshots/shareGenerates an unguessable, link-scoped share for a snapshot the caller owns (CD11). Returns the token + public deploy-from-link URL. This is the thin… - GETPreview a shared snapshot (public)
/snapshots/share/:tokenUnauthenticated preview of a shared snapshot, driving the public deploy-from-link page. Returns only the env description (paths, size, recency) — never the… - GETList the caller's snapshot shares
/snapshots/shares - POSTRevoke a snapshot share
/snapshots/share/:token/revoke - POSTSnapshot webhook
/snapshots/webhookWebhook endpoint for snapshot status updates from Ogre. - PATCHSet the visibility of a snapshot series
/snapshots/:source/visibilitySets private / team / public on every series behind a snapshot source (a deployment id or ext-<backupId>). Requires write access; a share link does not grant…
Billing
- GETGet team billing history
/billing/historyRetrieves a detailed history of billing events and transactions for the current team.
Referrals
- GETGet user referral code
/referrals/codeRetrieves the current user's unique referral code. - GETGet referral statistics
/referrals/statsRetrieves statistics about the user's referrals, including count and rewards. - GETGet referral history
/referrals/historyRetrieves the list of users who signed up with the caller's referral code, with masked emails, per-referral payout status, and credits earned. - POSTApply a referral code
/referrals/applyAllows a new user to apply a referral code within the allowed window.
Teams
- GETList user teams
/teamsRetrieves all teams the current user is a member of. - POSTCreate team
/teamsCreates a new team. - GETGet default team
/teams/defaultRetrieves the current user's default team. - GETGet team details
/teams/:teamIdRetrieves detailed information about a specific team, including members. - DELETEDelete team
/teams/:teamIdDeletes a team. Only the team owner may delete it.
API Keys
- GETList API Keys
/api-keys/teams/:teamIdLists all API keys for the team. - POSTCreate API Key
/api-keys/teams/:teamIdCreates a new API Key for the team. - DELETERevoke API Key
/api-keys/teams/:teamId/:keyIdRevokes (deletes) an API Key for the team. - POSTStart CLI device login
/api-keys/device/startBegins the aq login device-grant pairing. Public (unauthenticated): returns a secret deviceCode for polling and a short userCode the user approves in the… - POSTPoll CLI device login
/api-keys/device/tokenPolls a pairing by its deviceCode. Public. Returns { status } of pending | approved | denied | expired | consumed; on the first approved poll it returns the… - GETGet pairing details
/api-keys/device/:userCodeReturns pairing details (scopes, status) for the console approve screen. The requesting machine name is withheld until approval to avoid leaking it on a… - POSTApprove CLI device login
/api-keys/device/approveApproves a pairing as the signed-in user, minting an API key for the team named in teamId (owner/admin only) or, when absent, their default team, and staging… - POSTDeny CLI device login
/api-keys/device/denyDenies a pairing so the CLI stops polling.
Setups
- GETList snapshot versions you can see
/setups/versionsYour own versions plus any owned by a team you belong to. Pass ?public=true to fold in the public catalog, and ?name= to filter to one series. - GETThe public snapshot version catalog
/setups/versions/publicVersions whose owners published them. Readable and restorable by any authenticated user; never editable or deletable by anyone outside the owning team. - GETGet a snapshot version
/setups/versions/:idReturns 404 — not 403 — when you cannot read the version, so the response never confirms that another tenant's version exists. - PATCHEdit a snapshot version's metadata
/setups/versions/:idOnly label, description and visibility can change. A body carrying a pinned field (the snapshot id, path, series or version number) is REFUSED rather than… - GETList your deployments running a snapshot version
/setups/versions/:id/deploymentsRequires write access to the version, and returns only deployments the CALLER owns (their own plus their teams'). A public version may be running on other… - GETList pods
/setupsPods owned by the current team. - POSTCreate a pod and start it
/setupsCreates the pod, then starts it on the given offer, which rents a billable box. A start the deploy boundary refuses keeps the pod created and stopped, so… - GETGet a pod
/setups/:id - POSTStart a pod
/setups/:id/startRents a box on the given offer and answers 202 with the new deployment id. Needs an API key with the deploy or full scope. - POSTStop a pod
/setups/:id/stopQueues the stop and answers 202 at once.
Jobs
- GETList jobs
/jobsJobs owned by the current team. Pass ?shape=batch or ?shape=service to filter. - POSTCreate a job
/jobsCreates a job from a snapshot version or an image. A batch job runs once at create time; spending routes need an API key with the deploy or full scope. - POSTStart a run of a service job
/jobs/:id/runsQueues a run with the given inputs and answers 202. A batch job runs once; use rerun to run it again (409 here). - GETGet a run
/jobs/:id/runs/:runIdA run with its attempts, cost and any boxes that failed during placement. - GETPrice a job before creating it
/jobs/cost-preview?gpuModels=string&diskGb=10The hourly price of the cheapest machine matching the card type, from the live marketplace feed. Spends nothing. - GETLive availability by GPU model and count
/jobs/hardware-availabilityPer GPU model and count: how many offers and providers are eligible and the lowest price, from the live marketplace feed. Spends nothing.
Audit Log
- GETList your team audit log
/audit-logNewest-first page of mutating actions taken in the team named by the x-team-id header. Scoped to that one team; there is no way to read another team log. Page…
Feedback
- POSTSubmit Feedback
/feedbackSubmit platform feedback. At least one of liked, disliked, or comment must be provided.
API details
- Authentication
- A bearer token in the Authorization header
- Operations
- 84 operations on 71 pathsGET 45POST 30PATCH 5DELETE 4
- Main resources
- User Settings 15Setups 10Snapshots 10API Keys 8Connector 7Deployments 7Jobs 6Marketplace 5Teams 5Credits 4
- Response formats
application/json- Description format
- OpenAPI 3.0.0, API version
1.0.0 - Links
- OpenAPI document
- Listed from
- Aquanode's published OpenAPI description
How to test the Aquanode Orchestrator API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Aquanode Orchestrator API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Register a connector session” (POST /connector/sessions), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Aquanode Orchestrator API?
API documentation for the Aquanode deployment orchestrator. It is listed under Developer tools and has 84 endpoints.
Who publishes the Aquanode Orchestrator API?
It is listed from Aquanode's public API description (an OpenAPI document), not published by Aquanode on Swastik Codes. Anyone who controls aquanode.io can claim the profile by adding a DNS TXT record.
How do I authenticate with the Aquanode Orchestrator API?
With A bearer token in the Authorization header.
How many endpoints does the Aquanode Orchestrator API have?
84 operations on 71 paths (45 GET, 30 POST, 5 PATCH, 4 DELETE). The largest groups are User Settings, Setups, Snapshots, API Keys.
Is forking the Aquanode Orchestrator API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.