---
description: >-
  The Watcher HTTP API for programmatic access: base URL, authentication with organization API keys, browsing the endpoints, and the Python SDK binding.
---

> Part of the Watcher docs. Index of all pages, with summaries: https://watcher-docs.apolloresearch.ai/llms.txt
> Before upgrading Watcher, read the release pages and full changelogs for every version crossed: https://watcher-docs.apolloresearch.ai/releases/index.md
> Found an issue with this page? Report it: https://github.com/ApolloResearch/watcher-bin/issues/new?title=Docs%20feedback%3A%20API&body=Page%3A%20API%0AURL%3A%20https%3A%2F%2Fwatcher-docs.apolloresearch.ai%2Fapi%2F%0A%0A

# API

The Watcher HTTP API gives you programmatic access to your deployment's recorded
data and grading. You can query
[sessions](../concepts/sessions-and-trajectories.md),
[trajectories](../concepts/sessions-and-trajectories.md), and grades. You can
ingest trajectories from your own tooling. You can integrate gateways through
[gateway hooks](hooks.md). You can run [graders](../concepts/graders.md) on
demand. You can read or update
[organization settings](../concepts/organization-settings.md). Set custom instructions
for [managed monitors](../concepts/graders.md#monitors) through the
[monitor customization API](monitor-customization.md). Some
[Analyzer](../concepts/analyzer.md) administration is not on the API. API-key
and member management are handled by the sign-in provider's own components. The
[Python SDK](python-sdk.md) 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`:

```text
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](../concepts/organization-settings.md)). 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](python-sdk.md#reuse-a-saved-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.

```bash
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](python-sdk.md) 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](python-sdk.md) 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.