> ## 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. # API reference overview > Base URL, authentication, pagination, and compatibility for the Orca Agents API. This reference lists every route Orca supports, grouped by resource. If you are new to Orca, start with [how Orca works](/concepts) and the [quickstart](/quickstart); this section is for looking things up. | Page | Covers | | - | - | | [Agents](/reference/agents) | Saved agent configurations | | [Sessions](/reference/sessions) | Conversations, turns, items, subagents, artifacts | | [Events](/reference/events) | Sending input and streaming output | | [Resources](/reference/resources) | Environments, templates, files, skills, vaults | | [Errors](/reference/errors) | Error format and HTTP status codes | ## Base URL All paths in this reference are relative to the Orca base URL: ```text theme={"dark"} https://api.orcapods.ai/v1 ``` 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](#orca-extensions). ## Authentication Send your Orca API key as a bearer token on every request. A missing or invalid key returns `401`. ```bash theme={"dark"} curl -H "Authorization: Bearer $API_KEY" "$BASE_URL/agents?limit=10" ``` ```python theme={"dark"} from openai import OpenAI client = OpenAI(api_key="YOUR_ORCA_KEY", base_url="https://api.orcapods.ai/v1") ``` The key determines your [organization](/organizations) 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: | Parameter | Meaning | | - | - | | `limit` | Page size | | `order` | `asc` or `desc` | | `after` | The ID of the last item on the previous page | The response contains `object: "list"`, `data`, `first_id`, `last_id`, and `has_more`. While `has_more` is true, request the next page with `after=`. 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](https://developers.openai.com/api/docs/guides/agents-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](/reference/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](/plans#sessions-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. | Method | Path | Purpose | Guide | | - | - | - | - | | GET | `/v1/models` | Orca credit models, as `orca/openrouter/` | [Models](/providers#discover-orca-credit-models) | | GET | `/api/models` | Every model you can pick, grouped by who pays, with Orca credit prices | [Models](/providers#discover-orca-credit-models) | | GET, POST | `/api/sessions/{session_id}/model` | Read or switch the model one session's next turn uses | [Switch who pays](/providers#switch-who-pays-for-one-session) | | GET | `/api/providers`, `/api/providers/{provider}` | Supported providers and whether you have a key | [Provider keys](/providers#connect-a-provider) | | PUT, DELETE | `/api/providers/{provider}/key` | Set or remove a provider key (admin) | [Provider keys](/providers#connect-a-provider) | | GET | `/api/providers/{provider}/models` | That provider's model list | [Provider keys](/providers#connect-a-provider) | | GET | `/api/whoami` | The organization, person, and role your key acts as | | | GET, POST | `/api/keys` | List or create API keys. A new key's `secret` is returned once. | [Roles](/organizations#api-keys-carry-a-role) | | DELETE | `/api/keys/{key_id}` | Revoke a key | [Roles](/organizations#api-keys-carry-a-role) | | GET | `/api/billing/wallet` | Balance, plan, machine time, and packs on sale | [Wallet](/wallet#read-the-wallet-and-your-usage) | | POST | `/api/billing/checkout` | Start a Polar checkout for a pack or plan (admin) | [Wallet](/wallet#buy-credit) | | GET | `/api/billing/checkouts/{checkout_id}` | A checkout's state | [Wallet](/wallet#buy-credit) | | POST | `/api/billing/portal` | A link to Polar's billing portal (admin) | [Plans](/plans#change-your-plan) | | GET | `/api/usage`, `/api/usage/events` | Usage totals and rows, with their cost | [Wallet](/wallet#read-the-wallet-and-your-usage) | | | `/api/kits/...`, `/api/public/kits/{public_id}` | Make, publish, and copy kits | [Kits](/kits#routes) | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.