> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# SDKs
> Use the generated Orca SDKs to create profiles, launch runs, stream events, and manage platform resources from application code.
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.
Use `OrcapodsClient` from browser, Node.js, or dashboard-adjacent code.
Use the sync or async `orcapods` client.
Coming soon as a public module. The page covers status and calling the REST API from Go today.
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:
```bash theme={null}
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 → API Keys (see [API keys](/concepts/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 → API Keys | You call any non-local deployment; the tenant is derived from the key |
| Timeout | 60 seconds in TypeScript/Python; 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__` 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:
Call `health` to confirm the SDK can reach the configured base URL.
Use `profiles.create` for a custom agent, or `misc.seed_orca` / `SeedOrca` to restore the built-in Orca helper profile.
Submit a task with a profile name, title, and prompt. The conductor can mint `runId` and `sessionId` when they are empty.
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, and capability bundle discovery |
| Profiles | Reusable agent definitions, attached skills, and profile run history |
| Pools | Named agent pools and pool 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 one-time public API key issuance |
| 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 |
See the [SDK method map](/sdk/reference) 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.
```bash theme={null}
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.