TypeScript SDK
Getting Started
Drive Orca programmatically from any TypeScript or JavaScript codebase.
The SDK is in early alpha. It is not meant for production use and may be removed in the future. Stay on the latest version (@orca_sh/sdk@latest) while we iterate.
The Orca TypeScript SDK manages workspaces, tasks, projects, and automations from code. Common uses:
- Bulk task management: script the creation, triage, or cleanup of tasks across one or many projects.
- Integrations: sync tasks to/from your CRM, issue tracker, or internal tools.
- Provisioning: spin up workspaces on a developer's machine when an issue is opened, a PR is reviewed, or a customer ticket lands.
- On-demand agents: kick off a recurring automation off-schedule when a webhook fires.
The SDK is fully typed and works in Node, Bun, and Deno. It also runs in browsers, but do not ship sk_live_… keys to a frontend: they are long-lived and grant full org access. From a browser, call a server proxy that holds the key.
Install
npm install @orca_sh/sdkStay on the latest version rather than pinning. New methods get added; existing ones do not change shape without a version bump and a changelog note.
Get an API key
- Open the Orca desktop app → Settings → API Keys → Create. The key starts with
sk_live_…. Copy it now. It is shown only once. - Note your organization ID. Find it in the org switcher inside the desktop app.
export ORCA_API_KEY=sk_live_…
export ORCA_ORGANIZATION_ID=…Create the client
import Orca from '@orca_sh/sdk';
const client = new Orca();
// reads ORCA_API_KEY and ORCA_ORGANIZATION_ID from envEvery resource works the same way:
// Create a task
const task = await client.tasks.create({
title: 'Wire up auth',
priority: 'high',
});
// Update it
await client.tasks.update({ id: task.id, statusId: '<uuid>' });
// Look one up by id or slug
const got = await client.tasks.retrieve('SUPER-172'); // returns null if missing
// Find tasks with rich filters
const urgent = await client.tasks.list({
priority: 'urgent',
search: 'auth',
creatorMe: true,
});
// Inspect what else you have: projects and workspaces are host-owned
const [host] = await client.hosts.list();
if (!host) throw new Error('No hosts registered; run `orca start` on a machine');
const projects = await client.projects.list({ hostId: host.id });
const automations = await client.automations.list();
// Trigger an automation off-schedule
await client.automations.run('<automation-id>');
// Create a workspace on a developer's machine
await client.workspaces.create({
hostId: '<machine-id>',
projectId: '<project-id>',
name: 'fix-auth-bug',
branch: 'fix/auth',
});See the reference for every method, parameter, and return type.
Configuration
Configure the client explicitly instead of (or with) the env vars:
const client = new Orca({
apiKey: 'sk_live_…',
organizationId: '…',
timeout: 60_000, // default: 60s per request
maxRetries: 2, // default: 2 retries with exponential backoff
logLevel: 'warn', // 'off' | 'error' | 'warn' | 'info' | 'debug'
});The client retries automatically on network errors and 429/5xx responses.
Handling errors
The SDK throws typed errors for any non-success response:
import Orca, { APIError, NotFoundError, RateLimitError } from '@orca_sh/sdk';
const client = new Orca();
try {
await client.tasks.create({ title: '' });
} catch (err) {
if (err instanceof RateLimitError) {
// 429: already retried up to maxRetries; back off further if you keep hitting it
} else if (err instanceof NotFoundError) {
// 404
} else if (err instanceof APIError) {
// anything else: err.status, err.headers, err.error (the parsed body)
console.error(`Orca returned ${err.status}:`, err.error);
}
}