Build with the HivemindOS backend

The HivemindOS SuperAgent API lets your server use managed HivemindOS features. It does not control a user’s computer or open a desktop session.

Choose what you want to build

Quickstart

Connect an MCP-compatible agent

Add https://api.hivemindos.app/mcp as a remote Streamable HTTP server and send your restricted SuperAgent API key in the protected Authorization header. The agent receives four tools: list services, search allowed actions, read, and act. Your key’s scopes, service and operation boundaries, project, endpoint limits, approvals, and Agent Credit balance apply unchanged.

See Connect an agent with MCP for a ready-to-copy configuration and a least-privilege key example.

Let your agent configure it

Open the copy-paste agent setup file, copy the whole page, and paste it into the coding agent working on your project. It tells the agent how to inspect your project, create a restricted key, add the client, protect secrets, discover live capabilities, and verify the integration.

If the agent supports reusable skills, download the SuperAgent API SKILL.md. It teaches the agent how to keep managing keys, limits, capabilities, funding, tests, and audits after the first setup.

The agent must still ask before signing or sending an x402 payment. See the agent setup guide if you want to review the steps first.

Install the TypeScript SDK

npm install @hivemindos/sdk

The API also works with any HTTPS client. All examples use JSON unless a database archive is being uploaded or downloaded.

Create the first API key

Use an existing HivemindOS credit token once to create a SuperAgent API key. The key below can use research and managed databases, but nothing else.

import { createHivemindOSApiKey } from "@hivemindos/sdk";

const result = await createHivemindOSApiKey({
  creditToken: process.env.HIVEMINDOS_CREDIT_TOKEN!,
  idempotencyKey: "my-backend-root-key-v1",
  label: "My backend",
  scopes: [
    "services:read",
    "services:invoke",
    "databases:read",
    "databases:write",
    "credits:read",
    "api_keys:manage",
  ],
  allowedServices: ["hive-research", "hivemind-database"],
  allowedOperations: [
    "services.list",
    "capabilities.list",
    "actions.list",
    "services.invoke.hive-research.analyses.create",
    "databases.account.read",
    "databases.query",
  ],
  limits: {
    "*": { requestsPerHour: 1_000, maxConcurrent: 10 },
    "services.invoke.hive-research.analyses.create": {
      requestsPerMinute: 60,
      maxConcurrent: 2,
    },
    "databases.actions": { requestsPerDay: 500 },
  },
});

if (!result.ok) throw new Error(result.error);

// The complete secret is returned only when the key is created.
// Save it in your server-side secret manager.
const apiKey = result.secret;

Keys begin with hmos_live_. Never place one in a browser bundle, mobile binary, public repository, log, or analytics event.

Call the API

import { HivemindOSClient } from "@hivemindos/sdk";

const hive = new HivemindOSClient({
  apiKey: process.env.HIVEMINDOS_API_KEY!,
  projectId: process.env.HIVEMINDOS_PROJECT_ID,
});

const catalog = await hive.services.list();
if (!catalog.ok) throw new Error(catalog.error);

const research = await hive.services.invokeOperation(
  "hive-research",
  "analyses.create",
  { question: "Summarize the strongest evidence for this thesis." },
  { idempotencyKey: "research-thesis-001" },
);

if (!research.ok) throw new Error(research.error);

The equivalent authentication header is:

Authorization: Bearer hmos_live_...

Every mutation and spending action also requires a unique Idempotency-Key header.

Read the result

JSON endpoints return a stable success or failure envelope:

{
  "ok": true,
  "services": []
}

{
  "ok": false,
  "error": "This API key does not have access to that managed service."
}

Check ok before reading the result. Failures may also include code, operationId, metric, and retryAfterSeconds so your app can choose the right next action.

Understand payment

Every API key belongs to one HivemindOS account. Paid API work uses that account’s Agent Credits. A request cannot charge a different account or choose its own price.

Managed database capacity follows the account’s eligible plan. Wallet assets are separate: Agent Credits pay for managed work, while wallet assets pay transfer amounts, network fees, and trades.

Use GET /pricing for the current price and GET /credits/balance for the current balance. Show the returned final or maximum price before paid work starts.

An API key with credits:write can buy more Agent Credits through POST /credits/x402/top-up. The API returns a standard x402 challenge, accepts a signed Base payment, and adds the purchased credits to that key’s existing HivemindOS account. HivemindOS fixes the official revenue recipient, network, asset, price, and credited account on the server, so the caller cannot redirect a payment or fund another account.

Continue

• Authentication and API keys
• Copy-paste agent setup
• Connect an agent with MCP
• Projects, isolation, and service accounts
• Service access and catalog
• Managed memory and knowledge
• Capabilities, agents, workflows, and mini apps
• Hive Compute marketplace, privacy tiers, MCP, and testnet assets
• Per-endpoint limits
• Files, connections, and integrations
• Managed databases
• Wallets, approvals, and trading
• Runs, artifacts, webhooks, and errors
• Usage and audit events
• Endpoint and scope reference

The OpenAPI contract remains authoritative for request and response schemas.