Skip to main content
This reference lists every route Orca supports, grouped by resource. If you are new to Orca, start with how Orca works and the quickstart; this section is for looking things up.

​
Base URL

All paths in this reference are relative to the Orca base URL:
The official clients take this as base_url (Python) or baseURL (TypeScript). Agents, sessions, environments, and vaults are under client.beta.agents; files and skills are under client.files and client.skills. Orca’s own extensions live outside /v1; see Orca extensions.

​
Authentication

Send your Orca API key as a bearer token on every request. A missing or invalid key returns 401.
The key determines your organization and your role in it. You only see your organization’s resources; anything else returns 404. An action your role does not allow returns 403. Keep keys out of source control. Create keys in the dashboard under Settings, API keys, with orca keys create, or with POST /api/keys. JSON requests use Content-Type: application/json. File and skill uploads use multipart/form-data.

​
Pagination

Most list endpoints use cursor pagination: The response contains object: "list", data, first_id, last_id, and has_more. While has_more is true, request the next page with after=<last_id>. The Python and TypeScript clients do this for you when you iterate the result. Some lists take extra filters: sessions accept agent_id, artifacts accept environment_id, and vaults and credentials accept status. Environment file listing is different. Its response has data, has_more, and an opaque next token. Pass next as page to get the following page, not after.

​
Compatibility

Orca implements the OpenAI Agents API. The OpenAI Agent API quickstart is useful background, but Orca is a separate implementation:
  • Supported routes are exactly those listed in this reference. They were checked against the official clients at Python openai 3.13.0 and TypeScript openai 7.15.0.
  • Other client versions may add or rename methods that Orca does not support.
  • On hosted Orca, self_hosted environments are coming soon, network.access: "restricted" is not available, and remote MCP servers are currently blocked.
  • Event payloads: Orca sends the event types listed in events. Handle unknown event types gracefully.

​
Rate limits

Each key can make 300 requests a minute, and each organization 600. Past that, requests return HTTP 429 rate_limit_exceeded, “Rate limit reached. Retry after N seconds.”, with a Retry-After header. Your plan also limits how many sessions run at once.

​
Orca extensions

These routes are Orca’s own, outside the OpenAI Agents API. They live at https://api.orcapods.ai, without /v1. Call them with plain HTTP and the same bearer key; the openai clients have no methods for them.