SuperAgent API
SuperAgent API reference
This is the complete technical route map. If you are making your first call, start with the plain-language overview. Use this page when you need an exact scope, endpoint, header, or limit selector.
The OpenAPI 3.1 document is the source of truth for request and response shapes. It can also generate clients, validators, and API explorers.
Base URL: https://api.hivemindos.app/v1
MCP URL: https://api.hivemindos.app/mcp
Authentication: Authorization: Bearer hmos_live_...
Content type: application/json
Database archive parts and downloads use application/zip instead of JSON.
Public endpoints
| Method | URL | Purpose |
|---|---|---|
GET |
https://api.hivemindos.app/health |
Service and API-version health. |
GET |
https://api.hivemindos.app/openapi.json |
OpenAPI 3.1 contract. |
POST |
https://api.hivemindos.app/mcp |
Authenticated Streamable HTTP MCP transport. Requires services:read and actions.list. |
GET |
/pricing |
Server-owned price and availability catalog. Optional service query: platform-api, managed-wallets, managed-trading, managed-agents, or managed-workflows. |
The health and OpenAPI documents are also available under /v1. Pricing is public and does not accept client-supplied prices.
Scopes
| Scope | Allows |
|---|---|
services:read |
List managed services visible to the key. |
services:invoke |
Invoke an allowed generic managed service. |
credits:read |
Read the account’s HivemindOS credit balance. |
credits:write |
Buy Agent Credits for the authenticated account through x402. |
projects:read |
List and read projects visible to the key. |
projects:write |
Create, update, and archive projects. |
usage:read |
Read project request and charged-credit summaries. |
audit:read |
Read project request audit events. |
files:read |
List and download project files. |
files:write |
Upload and delete project files. |
connections:read |
Read protected connection metadata. |
connections:write |
Create, rotate, disable, and delete protected connections. |
databases:read |
Read database status, structure, records, transfers, and archives. |
databases:write |
Provision or change database data and manage portable copies. |
wallets:read |
List wallets, read one wallet, and read balances. |
wallets:create |
Create a managed wallet. |
wallets:sign |
Quote and execute approved message signatures. |
wallets:transact |
Quote and execute wallet sends and swaps. |
trading:read |
Read managed trading positions. |
trading:execute |
Quote and submit managed spot trades. |
runs:read |
List and read durable service runs. |
runs:write |
Create and cancel durable service runs. |
approvals:read |
List approvals visible to the account. |
approvals:write |
Approve or reject actions and administer wallet policy. |
artifacts:read |
List and download authenticated run artifacts. |
webhooks:read |
List webhooks manageable by the key. |
webhooks:write |
Create and disable webhooks. |
api_keys:manage |
Create narrower child keys and list or revoke the current key and descendants. |
Endpoint map
Idem means a valid Idempotency-Key header is required. Limit operation is the selector used in API-key limits.
API keys, services, and credits
| Method and path | Scope | Idem | Limit operation |
|---|---|---|---|
GET /api-keys |
api_keys:manage |
No | apiKeys.list |
POST /api-keys |
First-key credit token or api_keys:manage |
Yes | apiKeys.create |
DELETE /api-keys/{id} |
api_keys:manage |
Yes | apiKeys.revoke |
GET /services |
services:read |
No | services.list |
GET /capabilities |
services:read |
No | capabilities.list |
GET /capabilities/{serviceId} |
services:read and service access |
No | capabilities.list |
GET /actions |
services:read |
No | actions.list |
POST /services/{serviceId}/invoke |
services:invoke and service access |
Yes | services.invoke, services.invoke.<serviceId> |
GET /credits/balance |
credits:read |
No | credits.balance.read |
POST /credits/x402/top-up |
credits:write |
Yes | credits.x402.topUp |
A registered managed operation also applies services.invoke.<serviceId>.<operationId>. Successful invocation responses include serviceId, operationId, upstream status, result, and the exact chargedCredits reported by the owning service.
Projects, usage, files, and connections
| Method and path | Scope | Idem | Limit operation |
|---|---|---|---|
GET /projects |
projects:read |
No | projects.list |
POST /projects |
projects:write |
Yes | projects.create |
GET /projects/{projectId} |
projects:read |
No | projects.read |
PATCH /projects/{projectId} |
projects:write |
Yes | projects.update |
DELETE /projects/{projectId} |
projects:write |
Yes | projects.archive |
GET /usage |
usage:read |
No | usage.read |
GET /audit-events |
audit:read |
No | auditEvents.list |
GET /files |
files:read |
No | files.list |
POST /files |
files:write |
Yes | files.create |
GET /files/{fileId} |
files:read |
No | files.read |
DELETE /files/{fileId} |
files:write |
Yes | files.delete |
GET /connections |
connections:read |
No | connections.list |
POST /connections |
connections:write |
Yes | connections.create |
GET /connections/{connectionId} |
connections:read |
No | connections.read |
PATCH /connections/{connectionId} |
connections:write |
Yes | connections.update |
DELETE /connections/{connectionId} |
connections:write |
Yes | connections.delete |
Managed databases
All database endpoints also require service access to hivemind-database.
| Method and path | Scope | Idem | Limit operation |
|---|---|---|---|
GET /databases/account |
databases:read |
No | databases.account.read |
POST /databases/account |
databases:write |
Yes | databases.account.provision |
DELETE /databases/account |
databases:write |
Yes | databases.account.deprovision |
POST /databases/query |
databases:read |
No | databases.query |
POST /databases/actions |
databases:write |
Yes | databases.actions |
POST /databases/transfers |
databases:write |
Yes | databases.transfers.create |
PUT /databases/transfers/{transferId}/parts/{partNumber} |
databases:write |
Yes | databases.transfers.part.upload |
POST /databases/transfers/{transferId}/complete |
databases:write |
Yes | databases.transfers.complete |
GET /databases/transfers/{transferId}/archive |
databases:read |
No | databases.transfers.archive |
GET /databases/transfers/{transferId} |
databases:read |
No | databases.transfers.read |
DELETE /databases/transfers/{transferId} |
databases:write |
Yes | databases.transfers.cancel |
Managed wallets and trading
Wallet endpoints require service access to managed-wallets. Trading endpoints require service access to managed-trading.
| Method and path | Scope | Idem | Limit operation |
|---|---|---|---|
GET /wallets |
wallets:read |
No | wallets.list |
POST /wallets |
wallets:create |
Yes | wallets.create |
GET /wallets/{walletId} |
wallets:read |
No | wallets.read |
GET /wallets/{walletId}/balances |
wallets:read |
No | wallets.balances.read |
PATCH /wallets/{walletId}/policy |
approvals:write |
Yes | wallets.policy.update |
POST /wallets/{walletId}/transactions/quote |
wallets:transact |
Yes | wallets.transactions.quote |
POST /wallets/{walletId}/transactions |
wallets:transact |
Yes | wallets.transactions.create |
GET /wallets/{walletId}/transactions |
wallets:read |
No | wallets.transactions.list |
GET /wallets/{walletId}/transactions/{transactionId} |
wallets:read |
No | wallets.transactions.read |
POST /wallets/{walletId}/signatures/quote |
wallets:sign |
Yes | wallets.signatures.quote |
POST /wallets/{walletId}/signatures |
wallets:sign |
Yes | wallets.signatures.create |
POST /trading/quotes |
trading:execute |
Yes | trading.quotes.create |
POST /trading/orders |
trading:execute |
Yes | trading.orders.create |
GET /trading/orders |
trading:read |
No | trading.orders.list |
GET /trading/orders/{orderId} |
trading:read |
No | trading.orders.read |
GET /trading/positions |
trading:read |
No | trading.positions.list |
Runs, approvals, artifacts, and webhooks
Run and artifact reads also require service access to the resource’s source service.
| Method and path | Scope | Idem | Limit operation |
|---|---|---|---|
GET /runs |
runs:read |
No | runs.list |
POST /runs |
runs:write and service access |
Yes | runs.create, runs.create.<serviceId> |
GET /runs/{runId} |
runs:read |
No | runs.read |
POST /runs/{runId}/cancel |
runs:write |
Yes | runs.cancel |
GET /approvals |
approvals:read |
No | approvals.list |
POST /approvals/service-actions |
approvals:write and service access |
Yes | approvals.create |
POST /approvals/{approvalId} |
approvals:write |
Yes | approvals.decide |
GET /artifacts |
artifacts:read |
No | artifacts.list |
GET /artifacts/{artifactId}/content |
artifacts:read |
No | artifacts.content.read |
GET /webhooks |
webhooks:read |
No | webhooks.list |
POST /webhooks |
webhooks:write |
Yes | webhooks.create |
PATCH /webhooks/{webhookId} |
webhooks:write |
Yes | webhooks.update |
POST /webhooks/{webhookId}/rotate-secret |
webhooks:write |
Yes | webhooks.rotate |
DELETE /webhooks/{webhookId} |
webhooks:write |
Yes | webhooks.disable |
GET /webhook-deliveries |
webhooks:read |
No | webhookDeliveries.list |
POST /webhook-deliveries/{deliveryId}/replay |
webhooks:write |
Yes | webhookDeliveries.replay |
Limit operation ids
The wildcard selector * matches every authenticated operation. The complete static set is:
services.list
capabilities.list
services.invoke
credits.balance.read
credits.x402.topUp
projects.list
projects.create
projects.read
projects.update
projects.archive
usage.read
auditEvents.list
files.list
files.create
files.read
files.delete
connections.list
connections.create
connections.read
connections.update
connections.delete
apiKeys.list
apiKeys.create
apiKeys.revoke
databases.account.read
databases.account.provision
databases.account.deprovision
databases.query
databases.actions
databases.transfers.create
databases.transfers.part.upload
databases.transfers.complete
databases.transfers.archive
databases.transfers.read
databases.transfers.cancel
wallets.list
wallets.create
wallets.read
wallets.balances.read
wallets.policy.update
wallets.transactions.quote
wallets.transactions.create
wallets.transactions.list
wallets.transactions.read
wallets.signatures.quote
wallets.signatures.create
trading.quotes.create
trading.orders.create
trading.orders.list
trading.orders.read
trading.positions.list
runs.list
runs.create
runs.read
runs.cancel
approvals.list
approvals.create
approvals.decide
artifacts.list
artifacts.content.read
webhooks.list
webhooks.create
webhooks.update
webhooks.rotate
webhooks.disable
webhookDeliveries.list
webhookDeliveries.replay
For every service id, two exact selectors are also valid:
services.invoke.<serviceId>
runs.create.<serviceId>
services.invoke.<serviceId>.<operationId>
runs.create.<serviceId>.<operationId>
The SDK exports the expanded list as HIVEMINDOS_PLATFORM_OPERATION_IDS and exports the four operations that accept creditsPerDay as HIVEMINDOS_PLATFORM_CREDIT_METERED_OPERATION_IDS.
Request headers
| Header | When to send |
|---|---|
Authorization: Bearer <key> |
Every authenticated request. |
Content-Type: application/json |
JSON request bodies. |
Content-Type: application/zip |
A database transfer part. |
Content-Type: <media-type> |
A managed file upload. |
Content-Length |
A database transfer part or file upload. |
Idempotency-Key |
Every endpoint marked Yes above. |
X-HivemindOS-Project |
Select an active project with an account-level key. |
X-File-Name |
Required customer-visible file name for a file upload. |
X-Content-Sha256 |
Optional expected file checksum. |
X-HivemindOS-File-Purpose |
Optional project-defined file purpose. |
X-HivemindOS-Credit-Token |
Only while bootstrapping the first API key. |
Payment-Signature |
x402 v2 signed payment on the retry after an HTTP 402 challenge. Normally added by an x402-aware client. |
X-PAYMENT |
Legacy x402 payment header for compatible clients. |
X402-Version |
Optional x402 protocol-version hint. |
Response headers
| Header | Meaning |
|---|---|
Idempotent-Replayed: true |
This successful response came from an earlier request with the same key and input. |
Retry-After |
Seconds before the exhausted API-key window or capacity may be available. |
X-HivemindOS-Limit-Operation |
Exact operation id reported with HTTP 429. |
X-HivemindOS-Credits-Charged |
Authoritative managed-service charge when the operation reports one. |
X-HivemindOS-Upstream-Request-Id |
Safe managed-service request correlation id when available. |
X-Content-Sha256 |
SHA-256 checksum for a database archive download. |
X-HivemindOS-Archive-Public-Key |
Provenance key supplied with a database archive download. |
X-HivemindOS-Event |
Webhook event name. |
X-HivemindOS-Signature |
Timestamp and HMAC for a webhook delivery. |
Payment-Required |
Base64-encoded x402 v2 payment requirements on HTTP 402. |
Payment-Response |
x402 settlement result after a successful payment. |
X-HivemindOS-Paid-Agent-Receipt |
HivemindOS Agent Credit purchase receipt id. |
x402 Agent Credit top-up
Send { "amountUsd": 5 } to POST /credits/x402/top-up with an API key that has credits:write, an Idempotency-Key, and access to credits.x402.topUp. Amounts may be $5 to $500 with no more than two decimal places.
The first request returns HTTP 402 and Payment-Required. An x402 v2 client signs the exact Base payment and retries the same request with Payment-Signature and the same idempotency key. A successful response includes creditedUsd, creditedCredits, receiptId, and the updated credits balance.
The route never accepts a recipient, network, asset, price, credit token, or alternate account in its body. Those values are fixed and verified by HivemindOS, and the payment settles to the same official HivemindOS revenue wallet used by the other managed x402 services.
SDK constants and helpers
import {
HIVEMINDOS_PLATFORM_API_BASE_URL,
HIVEMINDOS_PLATFORM_API_VERSION,
HIVEMINDOS_SUPERAGENT_MCP_URL,
HIVEMINDOS_PLATFORM_SCOPES,
HIVEMINDOS_PLATFORM_SERVICE_IDS,
HIVEMINDOS_PLATFORM_OPERATION_IDS,
HIVEMINDOS_PLATFORM_CREDIT_METERED_OPERATION_IDS,
HIVEMINDOS_DATABASE_CONFIRMATIONS,
HivemindOSClient,
createHivemindOSApiKey,
hivemindOSRunCreateOperationId,
hivemindOSServiceInvocationOperationId,
} from "@hivemindos/sdk";
The SDK returns the same { ok: true, ... } or { ok: false, error, ... } envelopes as the HTTPS API. It does not throw for an ordinary API failure; check ok before using the result.
Return to the SuperAgent API quickstart, or open authentication, limits, databases, wallets and trading, or runs and webhooks.