SDKs - Orca

The Orca SDKs are generated from the public Conductor OpenAPI contract and wrap the same tenant-scoped HTTP API used by the dashboard. Use them when you want typed client code instead of hand-written fetch, curl, or http.Client calls.

TypeScript

Use OrcapodsClient from browser, Node.js, or dashboard-adjacent code.

Python

Use the sync or async orcapods client.

Go

Coming soon as a public module. The page covers status and calling the REST API from Go today.

VirtualFS

Talk to the standalone VirtualFS server: Python, TypeScript, plus the Claude and OpenAI Agents adapters.

When to use an SDK

Use an SDK for:

Onboarding users into a workspace by creating their first profile and run.
Building product workflows that submit agent tasks and render streaming progress.
Internal automation for tenants, pods, skills, MCP servers, secrets, memory, and storage.
Test fixtures that need a typed client against a local conductor.

Use direct HTTP when:

You are debugging the raw API shape.
You need an endpoint before the SDKs have been regenerated.
You are integrating from a language that does not have a generated SDK yet.

Setup model

All SDKs target the Conductor base URL. The hosted default is:

https://api.orcapods.ai

Each SDK authenticates with an ao_ bearer API key, sent as Authorization: Bearer ao_.... The tenant is derived from that key: the server strips any client-supplied X-Tenant-ID, so you cannot select a tenant from the client. Create keys in the dashboard under Settings, then API Keys (see API keys).

Concern	Default	Configure when
Base URL	`https://api.orcapods.ai`	You self-host the conductor behind another hostname or proxy
API key	`ao_` bearer token from Settings, then API Keys	You call any non-local deployment; the tenant is derived from the key
Timeout	60 seconds in Python by default (no default in TypeScript unless you set `timeoutInSeconds`, so an unconfigured TypeScript call can hang indefinitely); Go depends on your `http.Client` and context	Runs or streams can stay open longer than one minute
Retries	Generated SDK retry defaults	You need stricter latency or lower duplicate-request tolerance

Orca does not require an API key in the local development stack. In production, pass a tenant API key as the SDK bearer token. These keys use the ao_<env>_<random> format, inherit the minter’s RBAC role, and require the conductor to run with Postgres plus AGENT_API_KEY_PEPPER.

First workflow

The core onboarding flow is the same in every language:

Check the conductor

Call health to confirm the SDK can reach the configured base URL.

Create or seed a profile

Use profiles.create for a custom agent, or misc.seed_orca / SeedOrca to restore the built-in Orca helper profile.

Create a run

Submit a task with a profile name, title, and prompt. The conductor can mint runId and sessionId when they are empty.

Stream events

Subscribe to the run stream and handle progress, session_init, assistant, tool_call, tool_result, usage, result, and error events.

Generated resources

Every SDK exposes the same resource groups, with language-specific casing.

Resource	What it manages
Misc	Health checks, seeding Orca, capability bundle discovery, and identity lookup (whoami)
Profiles	Reusable agent definitions, attached skills, and profile run history
Pods	Named pods and pod membership
Sessions	Live agent sessions and their run history
Runs	Task submission, run lookup, cancellation, event replay, and live SSE streaming
Workflows	Workflow run creation, start/cancel/repair operations, run streaming, definitions, and schedules
Skills	Skill CRUD and skill resource files
MCP	Workspace MCP server registration, testing, updates, and deletion
Storage	Tenant-scoped object storage
Memory	Profile memory CRUD, search, and memory-bank snapshots
Secrets	Tenant-scoped secret CRUD
API Keys	Tenant-scoped control-plane API key listing, issuance, and revocation
Publishing	Published-agent configuration and public API key issuance, listing, and revocation
Billing	Credit wallet lookup and Polar checkout startup
Connected Apps	Provider discovery, connection initiation, connection repair, and connection deletion
Topology	Current conductor/runner topology
Stats	Dashboard summary, agent, time-series, and hotspot metrics
Spend Caps	Tenant spend-cap retrieval and update

See the SDK method map for the per-language names.

Regeneration

The SDKs are generated by Fern from docs/openapi.sdk.yaml using fern/generators.yml. The SDK spec is derived from the canonical full spec and strips operator-only, webhook, maintenance, and service-callback operations before generation.

make sdks

Use make sdk-spec when you only need to refresh docs/openapi.sdk.yaml. Generated SDK output is checked into:

sdks/typescript
sdks/python (the Python package modules live under sdks/python/src/orcapods)
sdks/go

The Fern Python generator currently writes modules flat into sdks/python; after regeneration, move generated package modules back under sdks/python/src/orcapods and leave pyproject.toml, README.md, and other package-root files at sdks/python. Do not hand-edit generated SDK files for user-facing behavior. Update the OpenAPI contract or generator config, regenerate, then update these docs if method names or request shapes change.

TypeScript

Python

Go

VirtualFS

​When to use an SDK

​Setup model

​First workflow

​Generated resources

​Regeneration

When to use an SDK

Setup model

First workflow

Generated resources

Regeneration