Private and confidential access

The SuperAgent API has three base URLs. They are the same API with the same paths, and each one offers only what meets its privacy level.

Each tier includes everything the stricter tiers do. Replace /v1 with the tier’s base in any path: /v1/private/services/cloud-superbrain/invoke is the private version of /v1/services/cloud-superbrain/invoke.

What each tier includes

The catalog, capabilities, actions, MCP tools and OpenAPI document under a tier’s base list only what that tier includes. Read them from the base you will call:

GET https://api.hivemindos.app/v1/private/catalog

Every capability also shows the strictest tier it serves in its privacy field.

Hive Compute serves every tier. Under the private and confidential bases it runs only on hosts with fresh verified hardware attestation, whatever the request’s own privacy setting says.

In the confidential tier:

• Chat and Memory Answer use only models that run in an attested enclave. The provider checks the enclave’s attestation on every request. A reply that arrives without that check is discarded, and you are not charged for it.
• Memory Answer has no default reader there, because the default reader is private but not attested. Name one from memory.models under the confidential base as model.
• Memories you write are never sent to an embedding model. Recall finds them by keyword, so Semantic Recall is refused with 409.
• Media models are listed and jobs can be read, but nothing is generated: no media model runs in attested hardware yet.

Models

Every model in the managed catalog has a privacy_level: standard, private or confidential. Under a tier’s base, managed-models models.list returns only the models that meet it, and a chat that names any other model is refused before anything is charged.

A model is private when its provider publishes that it keeps no prompts or replies, or when HivemindOS runs it. It is confidential when it also runs in an enclave whose attestation is checked on every request; the provider names these models with a :private suffix. Models routed to other providers are standard.

Media generation follows the same rule: under the private base, the media catalog and /media/models list only the private media models, and a request for any other model is refused before anything is charged.

Memory Answer lets you choose its reader the same way. See managed memory.

Pin a key to a tier

A key created under a tier’s base URL is pinned to that tier. You can also set privacy when you create a key:

const privateKey = await hive.apiKeys.create(
  {
    label: "Private memory worker",
    scopes: ["services:read", "services:invoke"],
    allowedServices: ["cloud-superbrain"],
    privacy: "private",
  },
  { idempotencyKey: "private-memory-worker-v1" },
);

A pinned key works only in its tier or a stricter one, whichever base URL it calls. Every key created from it keeps the pin, and a child key cannot loosen it. Keys report their tier in privacy.

Ask for a tier by header

Send X-HivemindOS-Privacy: private or X-HivemindOS-Privacy: confidential to ask for a tier on any path. The strictest of the base URL, the header and the key’s pin applies. Nothing can loosen a tier.

When something is refused

An operation below the request’s tier is refused with 403 before anything runs or is charged:

{
  "ok": false,
  "code": "privacy_tier",
  "privacy": "private",
  "operationPrivacy": "standard",
  "error": "This operation is not available in the private tier: what it is given would reach a service that does not meet it. Use it through /v1, with a key that is not pinned to a tier."
}

Name managed operations by operationId in the private tiers. A raw service path that is not a published operation cannot be checked, so it is refused.

What HivemindOS keeps

A reply from a private model is kept for 15 minutes, so that a retry with the same idempotency key, or a recovery lookup, can still collect it after a dropped connection. Then the words are deleted and only the billing record stays. A retry after that is told the reply is gone. It never runs the model again or charges again. The API itself does not keep private replies for replay.

What you ask HivemindOS to store is kept as usual: memories, files, database records, and the saved results of runs. A memory keeps the strictest tier it was written in. Memory Answer reads it only with a reader that meets that tier, and one written in the confidential tier is never sent to an embedding model.

A run keeps the tier it was created in. An idempotency key used in one tier cannot be reused in another.

Next: create narrow API keys, use managed memory, or browse managed services.