Skip to main content
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, pools, 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:
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 → API Keys (see API keys).
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:
1

Check the conductor

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

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.
3

Create a run

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

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. 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.
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.