Platform API & SDK

The widget is the fastest way to put an agent in front of people. When a chatbox is not enough — you want to start runs from your own backend, build a custom UI, react to approvals, or wire agents into your workflows — use the platform API directly. It is the same API the console is built on.

API keys and tenancy

Programmatic access uses a tenant API key plus the tenant id on every call:

• Authorization: Bearer hive_… — create one in the console (tenant admin; POST /v1/api-keys). The secret is shown once. Revoke with DELETE /v1/api-keys/:id.
• X-Tenant-Id: <uuid> — the tenant the key belongs to. Every table is tenant-scoped with row-level security; a key never sees another tenant.
• Role gates apply per route (member, admin, owner); an API key acts with the role it was issued under.

/v1 basics

• Base path /v1, JSON bodies, RFC 9457 problem+json errors with a stable code.
• Lists paginate with ?cursor=&limit= (default 25, max 100) and return { items, next_cursor }.
• OpenAPI: GET /v1/openapi.json documents the whole surface; the SDK types are generated from the same Zod DTOs the API validates with.

The four resources you will use first

# All /v1 calls: API key + tenant
export HIVE="https://console.agenticworkforce.me"
export AUTH=(-H "Authorization: Bearer $HIVE_API_KEY" -H "X-Tenant-Id: $TENANT_ID")

# 1. Which agents can I talk to?
curl "$HIVE/v1/agents" "${AUTH[@]}"

# 2. Start a thread on one of them
curl -X POST "$HIVE/v1/threads" "${AUTH[@]}" -H "Content-Type: application/json" \
  -d '{"agent_id":"'"$AGENT_ID"'","title":"Order 4711"}'

# 3. Post a message → 202 { run_id, message_id }
curl -X POST "$HIVE/v1/threads/$THREAD_ID/messages" "${AUTH[@]}" -H "Content-Type: application/json" \
  -d '{"content":"Where is order 4711?"}'

# 4. Follow the run live (SSE, full vocabulary) …
curl -N "$HIVE/v1/runs/$RUN_ID/events?since=-1" "${AUTH[@]}" -H "Accept: text/event-stream"

# … or poll for the terminal state (+ steps)
curl "$HIVE/v1/runs/$RUN_ID" "${AUTH[@]}"

The platform SSE stream (/v1/runs/:id/events) carries the full event vocabulary — step and node events, retrieval results, tool arguments — because the caller is a trusted tenant member. The widget’s /v1/embed/runs/:id/events is the redacted subset of the same stream.

@hive/sdk (optional)

The raw REST calls above are the primary path and need nothing but an HTTP client. If you write TypeScript, @hive/sdk is a thin, dependency-light client over the same endpoints (Node ≥ 18, browsers, edge runtimes). Request types are the API’s own Zod-inferred DTOs; non-2xx responses throw a typed HiveApiError with status, code and detail.

# from the tarball / private registry your platform contact provides
npm install @hive/sdk

import { HiveClient } from '@hive/sdk';

const hive = new HiveClient({
  baseUrl: 'https://console.agenticworkforce.me',
  apiKey: process.env.HIVE_API_KEY!,     // hive_… — created once in the console
  tenantId: process.env.HIVE_TENANT_ID!,
});

// Pick an agent, open a thread, post a message: that is one governed run.
const { items: agents } = await hive.agents.list();
const thread = await hive.threads.create({ agent_id: agents[0]!.id });
const { run_id } = await hive.threads.postMessage(thread.id, {
  content: 'Summarise the open tickets for account 4711.',
});

// Stream the run …
for await (const event of hive.runs.events(run_id)) {
  if (event.type === 'llm.delta') process.stdout.write(String(event.text)); // RunEvent is { type, ...unknown }
  if (event.type === 'run.completed' || event.type === 'run.failed') break;
}

// … or wait for the terminal state.
const run = await hive.runs.waitForCompletion(run_id);
console.log(run.status, run.output);

Approvals and webhooks

// A run that hits an approval policy pauses (status: waiting_approval)
// and emits an approval.requested webhook. Decide it to resume:
const { items } = await hive.approvals.list({ status: 'pending' });
await hive.approvals.decide(items[0]!.id, { action: 'approve' });

// Subscribe your backend to platform events (secret returned once):
const endpoint = await hive.webhooks.create({
  url: 'https://api.acme.com/hive-events',
  events: ['run.completed', 'approval.requested'],
});

Verify deliveries with verifyWebhookSignature(secret, signatureHeader, rawBody) — the signature carries a timestamp and the helper enforces a replay window (300 s by default). Covered SDK surfaces: agents, threads, runs (SSE + cancel), workflows, approvals, evalSuites, outcomes, experiments, webhooks, embedKeys.

The full API documentation

This portal documents the embed surface exhaustively and the rest of the platform only as far as you need to get started. For everything else:

• GET https://console.agenticworkforce.me/v1/openapi.json — the live OpenAPI document for your deployment.
• The platform specification set (docs/04-api.md for the API surface, docs/03-agent-manifest.md for the agent manifest, docs/05-runtime.md for the run lifecycle and HITL, docs/07-embed.md for the embed design) — ask your platform contact for access to the repository or an exported copy.
• Support — how to reach the platform team.