Service access and catalog

The service catalog answers two questions: what can this key use, and is it ready now? Read it before showing a feature or starting work.

The result is already filtered to the key’s permissions. A service marked available can be used. A service marked setup-required needs the account owner to finish setup first. Do not repeatedly retry coming-soon or unavailable services.

const response = await hive.services.list({ probe: true });
if (!response.ok) throw new Error(response.error);

for (const service of response.services) {
  console.log(service.id, service.status, service.operations);
}

Media Studio and Photo Keyworder use the same HivemindOS Agent Credit balance as every other paid SuperAgent capability. A successful media-generation request reports its reserved credit charge, failed work returns the reservation, completed work settles the exact charge, and an idempotent replay never debits the balance again. Photo analysis is charged only after the result completes. Responses expose the authoritative charge in chargedCredits and X-HivemindOS-Credits-Charged.

Managed Media chooses the lowest-priced healthy route for the model you requested. If that route becomes unavailable, the same job can continue through another exact route without changing models or reserving credits twice. The quote shows both the expected price and the highest possible reservation inside this fallback plan; anything not spent is returned when the job finishes. A content or safety rejection does not try another route.

GPT Image 2 uses medium quality when quality is omitted. Use quality: "low" only when you deliberately want a cheaper draft, or quality: "high" when the finished image needs maximum detail. Automatic fallback preserves the selected quality instead of silently reducing it.

Here is the shortest safe flow for a balanced GPT Image 2 request:

const request = {
  model: "gpt-image-2-text-to-image",
  input: {
    prompt: "A polished studio photograph of a black honey jar",
    aspect_ratio: "1:1",
    // quality is optional; GPT Image 2 defaults to "medium"
  },
};

const quoted = await hive.services.invokeOperation(
  "managed-media",
  "quotes.create",
  request,
  { idempotencyKey: "honey-jar-quote-v1" },
);
const expectedPriceUsd = quoted.result.quote.priceUsd;

const created = await hive.services.invokeOperation(
  "managed-media",
  "generations.create",
  { ...request, maximumDebitUsd: quoted.result.quote.fallbackMaximumUsd },
  { idempotencyKey: "honey-jar-v1" },
);

const finished = await hive.services.invokeOperation(
  "managed-media",
  "generations.get",
  undefined,
  {
    pathParameters: { jobId: created.result.job.id },
    idempotencyKey: "honey-jar-status-v1",
  },
);

Poll generations.get until the job is finalized. finished.result.job.outputs contains ready-to-use media links. Managed GPT Image 2 files are kept for 30 days, so copy anything you need to retain longer into your own storage.

Invoke a service directly

Generic managed services use one SuperAgent API front door:

POST /v1/services/{serviceId}/invoke

Prefer a stable operation id from GET /capabilities/{serviceId}:

{
  "operationId": "analyses.create",
  "input": {
    "question": "What evidence would falsify this thesis?"
  }
}

Path parameters and query values stay separate from the input body:

{
  "operationId": "analyses.get",
  "pathParameters": { "analysisId": "analysis_123" },
  "query": { "includeSources": true }
}

The method may be DELETE, GET, PATCH, POST, or PUT and defaults to POST. path must begin with /. Send an idempotency key even when the selected managed-service operation is read-like; the Platform invocation itself is a protected mutation.

The response keeps the managed service result inside a predictable wrapper:

{
  "ok": true,
  "serviceId": "hive-research",
  "operationId": "analyses.create",
  "status": 200,
  "chargedCredits": 0,
  "result": {
    "ok": true,
    "report": {}
  }
}

chargedCredits is the exact completed charge reported by the owning service. It is 0 for free reads and for work that did not complete. The same value is available in X-HivemindOS-Credits-Charged and in usage and audit records.

Legacy reviewed paths remain supported for compatibility, but registered operations are safer: they validate the method and path template, work with exact API-key access, and remain discoverable. The SuperAgent API rejects account, payment, credential, administrative, and other private service routes.

Managed databases, wallets, and trading use dedicated Platform endpoints instead of the generic invocation route. Those endpoints provide narrower scopes and safer request contracts.

Cloud Superbrain uses registered operations for typed memory, evolution, lexical search, paid semantic recall, grounded answers, generations, capsules, and knowledge graphs. See managed memory and knowledge for the complete operation map and request examples.

Distillation is also fully operable through registered operations. Upload managed files with runs.create, inspect the outline with runs.get, commit the selected section ids with runs.select, advance the durable run with runs.step, and optionally publish the completed artifact with the approval-bound runs.share operation. shared.get reads only the published artifact; uploaded source files remain private.

Agent Swarm runs are durable too. Start a single-scenario run through the swarm service’s runs.create operation, then read it with runs.get. HivemindOS continues queued and running work in the background even if the calling app disconnects. runs.step remains available when an interactive client wants the lowest possible completion latency; repeated calls are safe and do not start duplicate work.

Photo Keyworder accepts an inline image for small requests or one managed JPEG, PNG, or WebP file up to 8 MB. Managed files avoid the JSON request limit and are the recommended path for normal photos:

const result = await hive.services.invoke(
  "photo-keyworder",
  {
    operationId: "photos.analyze",
    input: { context: "Describe only what is visible." },
    files: [{ fileId: uploadedPhoto.id }],
  },
  { idempotencyKey: "photo-analysis-2026-08-27" },
);

The analysis service does not retain the uploaded pixels. The managed file remains under your account until you delete it.

Create a durable run

Use POST /runs when the work should have a run id, status, result, and optional artifact:

const run = await hive.runs.create(
  {
    serviceId: "hive-research",
    operationId: "analyses.create",
    input: { question: "Map the strongest counterarguments." },
  },
  { idempotencyKey: "research-run-counterarguments-001" },
);

Direct invocation and durable runs have separate aggregate and exact limit selectors:

• services.invoke and services.invoke.<serviceId>
• runs.create and runs.create.<serviceId>
• services.invoke.<serviceId>.<operationId>
• runs.create.<serviceId>.<operationId>

This lets one key allow a service but cap direct calls and background runs differently.

Managed agents and workflows

Managed agents are persistent cloud services, not remote-control desktop sessions.

const created = await hive.services.invokeOperation(
  "managed-agents",
  "agents.create",
  { name: "Support operator", planId: "small", modelTier: "fast" },
  { idempotencyKey: "support-agent-v1" },
);

The managed-agent facade permits the account overview and tenant-owned /v1/agents... operations. Managed workflows are restricted to an agent’s /v1/agents/{agentId}/routines... operations.

const routine = await hive.services.invokeOperation(
  "managed-workflows",
  "routines.create",
  {
    name: "Daily inbox review",
    triggerKind: "cron",
    cronExpression: "0 9 * * *",
    timezone: "America/New_York",
    prompt: "Review new support requests and prepare a prioritized brief.",
  },
  { pathParameters: { agentId }, idempotencyKey: "support-daily-review-v1" },
);

Running and retained managed-agent time use the same account credit balance as other managed work. Read the current plan catalog through GET /pricing?service=managed-agents before creating an agent.

Lead Generation

leadgen-data is a live managed service for finding and enriching businesses without adding a separate data-provider account to your product. Every call uses the authenticated account’s HivemindOS balance and returns its completed charge through the normal Platform usage and audit records.

Read service availability and the current allowance before starting a batch:

const catalog = await hive.services.invokeOperation(
  "leadgen-data",
  "catalog.get",
  undefined,
  { idempotencyKey: "lead-catalog-2026-08-25" },
);

Discover businesses with a stable company identifier so usage can be governed per company:

const result = await hive.services.invokeOperation(
  "leadgen-data",
  "leads.discover",
  {
    companyId: "company_acme",
    query: "independent dental practices in Austin, Texas",
    maxResults: 10,
    regionCode: "US",
  },
  { idempotencyKey: "acme-austin-dentists-001" },
);

The registered operations are catalog.get, leads.discover, leads.nearby, and leads.enrich. Restrict production keys to only the operations they need, set per-operation request and concurrency limits, and retry uncertain requests with the original idempotency key. The service enforces its own per-call and daily safety ceilings and refunds work that fails before producing usable results.

Next: use Hive Compute and the testnet faucet, configure per-service and per-operation limits, or use durable runs and webhooks.