API

The Watcher HTTP API gives you programmatic access to your deployment's recorded data and grading: query sessions, trajectories, and grades, ingest trajectories from your own tooling, run graders on demand, and read or update organization settings. 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, and 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, but for tools and scripts use an API key.
• Proxy mode (self-hosted behind your own auth proxy): there are no Watcher API keys. Requests authenticate with whatever your reverse proxy requires, 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, 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>/, and each client method wraps one endpoint. Endpoints are grouped by tag: sessions, ingest, grade, monitors, graders, 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.