cerolabs-sdk

TypeScript SDK for Cero Labs — the agent-native API for on-demand domain expertise.

When your agent hits an edge case, cero.escalate() routes it to a verified human expert and returns a structured, schema-validated response.

Install

npm install cerolabs-sdk

Requires Node 18+.

Quick start

import { Cero, z } from 'cerolabs-sdk';

const cero = new Cero({ apiKey: process.env.CERO_API_KEY! });

// Define exactly what you need back
const schema = z.object({
  appeal_recommended: z.boolean(),
  appeal_strength: z.enum(['strong', 'moderate', 'weak', 'not_applicable']),
  reasoning: z.string(),
});

// Escalate and wait in one call
const result = await cero.escalateAndWait({
  domain: 'healthcare.rcm',
  query: 'Should we appeal this CO-50 denial for cardiac stress test?',
  context: { cpt: '93015', payer: 'Blue Cross' },
  schema,
  priority: 'standard',
});

// result.answer is fully typed
if (result.answer.appeal_recommended) {
  console.log(`Strength: ${result.answer.appeal_strength}`);
  console.log(`Reasoning: ${result.answer.reasoning}`);
}

API

new Cero({ apiKey, baseUrl?, timeoutMs?, fetch? })

Create a client. apiKey is required — get one at app.cerolabs.ai/dashboard/api-keys.

cero.escalate({ domain, query, context?, priority?, schema?, callbackUrl?, metadata? })

Creates an escalation and returns immediately. When a Zod schema is passed, it's converted to JSON Schema so the expert's UI renders structured form fields.

cero.waitForResolution(escalationId, { schema?, timeoutMs?, pollIntervalMs? })

Blocks until the expert resolves, or until timeoutMs (default 5 minutes) elapses. Uses server-side long-polling when available.

cero.escalateAndWait({ ... })

Shortcut — escalate plus wait, in one call. Returns the full resolution with typed answer.

cero.checkEscalation(escalationId)

Non-blocking status check. Returns the full escalation detail including resolution (if any).

cero.cancelEscalation(escalationId)

Cancel a pending or routed escalation.

cero.submitFeedback(escalationId, score, comment?)

Rate the expert's resolution (score 0–1). Feeds into quality routing.

cero.listEscalations({ status?, domain?, limit?, offset? })

List recent escalations for your tenant.

cero.listDomains()

Canonical list of supported domains.

cero.usage()

Current credit balance, tier, and usage counters.

Error handling

All API errors throw typed errors:

import { Cero, CeroError, CeroInsufficientCreditsError, CeroTimeoutError } from 'cerolabs-sdk';

try {
  await cero.escalate({ ... });
} catch (err) {
  if (err instanceof CeroInsufficientCreditsError) {
    // User needs to top up — show billing link
  } else if (err instanceof CeroTimeoutError) {
    // Escalation didn't resolve in time
  } else if (err instanceof CeroError) {
    console.error(err.status, err.detail);
  }
}

Credits & pricing

Every escalation costs credits — 1 for standard (30 min SLA), 3 for urgent (5 min), 1 for batch (24 hr). New tenants get 10 free credits. Top up at app.cerolabs.ai/dashboard/billing.

See also

• Cero Labs API reference
• MCP server (cerolabs-mcp) — for Claude Desktop, Cursor, Cline, etc.
• Domain skills (GitHub) — pre-packaged agents for healthcare, legal, sales, content moderation.

License

MIT