API

The Watcher HTTP API gives you programmatic access to your deployment's recorded data and grading. You can query sessions, trajectories, and grades. You can ingest trajectories from your own tooling. You can integrate gateways through gateway hooks. You can run graders on demand. You can read or update organization settings. Set custom instructions for managed monitors through the monitor customization API. Some Analyzer administration is not on the API. API-key and member management are handled by the sign-in provider's own components. The Python SDK is a typed binding over this same API. Anything the SDK does, you can also do with plain HTTP requests. On proxy-mode deployments, the SDK authenticates through a pre-configured HTTP client (see the SDK page).

Base URL and versioning

The API is served by your Watcher deployment under the /api path, with endpoints versioned under /v1:

https://<your-watcher-host>/api/v1/...

For a self-hosted deployment, that is the same hostname as your Analyzer. On Apollo's hosted cloud, the base is https://app.apolloresearch.ai/api.

Authentication

How you authenticate depends on your deployment's authentication mode:

• SSO mode (Apollo cloud, and self-hosted in SSO mode): send an organization API key in the x-api-key header. Admins create and revoke API keys on the Analyzer's Organization page (see organization settings). The API also accepts the short-lived Authorization: Bearer token from a user's sign-in. Use an API key for unattended services. Local Python integrations can reuse the installed Watcher login, including token refresh.
• Proxy mode (self-hosted behind your own auth proxy): there are no Watcher API keys. Requests authenticate with whatever your reverse proxy requires. This is exactly like every other request to the deployment.

curl -H "x-api-key: $WATCHER_API_KEY" \
  https://watcher.example.com/api/v1/sessions

Browsing the API

The API is described by an OpenAPI 3.1 document, openapi.json. The document is maintained and versioned with the SDK. The spec is not currently published as a standalone download.

The installed Python SDK is a complete, typed map of the same surface. Every endpoint appears as a module under watcher_sdk/_generated/api/<tag>/. Each client method wraps one endpoint. Endpoints are grouped by tag: sessions, ingest, grade, monitors, graders, hooks, organization, users, usage, tool-call-decisions, auth, health, version.

Calling the API directly, note two things:

• Endpoint paths are relative to the /api server prefix: /v1/sessions is https://<your-watcher-host>/api/v1/sessions on the wire.
• The two security schemes (ApiKeyAuth, BearerAuth) are the SSO-mode headers described above; in proxy mode your proxy's requirements apply instead.

The Python SDK

The Python SDK wraps this API with typed sync and async clients: each of its methods calls one endpoint, and it adds retries with backoff, auto-pagination, structured errors, and typed models on top. Its base_url is the base URL above, /api prefix included. If you are working in Python, start there; use the HTTP API directly from other languages or where a dependency is unwanted.