---
title: WatchFor OpenAPI 3.1 specification
description: The machine-readable OpenAPI 3.1 document for the WatchFor REST API — where to fetch it, what it contains, and how to generate a typed client or feed it to an AI agent.
canonical: https://watchfor.io/docs/api/openapi
---

# WatchFor OpenAPI 3.1 specification

The machine-readable OpenAPI 3.1 document for the WatchFor REST API — where to fetch it, what it contains, and how to generate a typed client or feed it to an AI agent.

The WatchFor REST API is described by a single **OpenAPI 3.1** document.
It is generated from the same code that serves the API, so it cannot drift
from what `/api/v1` actually does.

## Where to fetch it

| URL | Notes |
| --- | --- |
| `https://watchfor.io/openapi.json` | Canonical location. |
| `https://watchfor.io/.well-known/openapi.json` | Same document at the well-known path scanners and agents probe first. |
| `https://watchfor.io/api/v1/openapi.json` | Same document next to the API it describes. |

All three return `application/json`, are public, need no authentication and
carry no rate limit that a client-generation step could hit.

## What is inside

- **Every `/api/v1` endpoint** with a stable `operationId` and typed request
  and response schemas (worked examples live on these docs pages).
- **Security schemes** for Bearer API keys and OAuth 2.1, with the
  `read` / `write` scope each operation needs (`x-required-scope`).
- **Two servers**: production (`/api/v1`) and the no-auth
  [sandbox](/docs/api/sandbox), so you can exercise real shapes before you
  create a key.
- **Idempotency-Key** declared on every create operation, cursor pagination
  parameters on every paginated list (small, plan-capped collections —
  status pages, alert rules, locations, on-call and report schedules — come
  back whole), and the error envelope from
  [Errors & rate limits](/docs/api/errors).
- The deprecation policy and versioning rules from
  [Operations & reliability](/docs/api/operations) as `x-` extensions.

## Generate a client

**TypeScript**

```bash
npx openapi-typescript https://watchfor.io/openapi.json -o watchfor.d.ts
```

The official `watchfor` npm package is built exactly this way, so if you just
want a client, `npm install watchfor` is shorter. See the SDK section in the
[API overview](/docs/api).

**Python**

```bash
pip install watchfor
```

The PyPI package wraps the same specification. For a custom client, feed the
URL above to `openapi-python-client` or `datamodel-code-generator`.

**Any language**

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://watchfor.io/openapi.json -g go -o ./watchfor-go
```

Replace `go` with any generator name (`java`, `csharp`, `php`, `rust`, …).

## Use it with AI agents

Agents that support tool use can load the document directly: every operation
has an `operationId`, a summary and typed parameters, which is what
function-calling conversions need. If the agent speaks MCP, the
[MCP server](/docs/api/mcp) exposes the same operations as tools without any
conversion step; the [A2A agent](/docs/api/a2a) covers delegated tasks. A
short orientation for agents lives at
[watchfor.io/agents.md](https://watchfor.io/agents.md).

## Versioning

The document's `info.version` tracks the API version. Breaking changes ship
as a new path prefix with a 90-day overlap; see
[Operations & reliability](/docs/api/operations) for the full policy.

---

Canonical page: https://watchfor.io/docs/api/openapi · All docs: https://watchfor.io/docs · Site guide: https://watchfor.io/llms.txt