SuperAgent API reference

The complete map of scopes, endpoints, headers, and limit selectors. For your first call, start with the quickstart.

The OpenAPI 3.1 document is the source of truth for request and response shapes, and can 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

The health and OpenAPI documents are also available under /v1. Pricing is public and never accepts client-supplied prices.

Scopes

Endpoint map

Paths are relative to the API base. Idem means an Idempotency-Key header is required. Limit operation is the selector used in API-key limits.

API keys, services, and credits

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

Managed databases

All database endpoints also require service access to hivemind-database.

Managed wallets and trading

Wallet endpoints require service access to managed-wallets. Trading endpoints require service access to managed-trading.

Universal swaps

Swap endpoints require service access to universal-swaps. See universal swaps for the flows.

Runs, approvals, artifacts, and webhooks

Run and artifact reads also require service access to the resource’s source service.

Limit operation ids

The wildcard * matches every authenticated operation. The complete static set is:

services.list
capabilities.list
actions.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
swaps.tokens.list
swaps.quote
swaps.prepare
swaps.execute
swaps.list
swaps.read
swaps.routes.read
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 and registered operation, these 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 the five operations that accept creditsPerDay as HIVEMINDOS_PLATFORM_CREDIT_METERED_OPERATION_IDS.

Request headers

Response headers

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 on an ordinary API failure, so check ok before using the result.

Deprecation policy

New operations and response fields can be added at any time, so ignore fields you do not know. Before an operation is removed or changed incompatibly:

• It is marked deprecated in the public changelog, with what to use instead, at least 30 days before it stops working.
• Responses from it carry a Deprecation header, and a Sunset header with the date it stops working, for that whole period.
• It keeps working until the Sunset date.

Watch for the Deprecation header in your logs, so a removal never comes as a surprise.

Related

• Quickstart
• Authentication and limits
• Runs, webhooks, and errors