# API Reference

> The interactive reference for the canonical OpenAPI contract.

Source page: https://docs.replynodes.com/docs/api-reference

# API Reference

Use the interactive reference at [/reference](https://docs.replynodes.com/reference). It is backed by the runtime capability OpenAPI contract copied to `/api/openapi.json` during the docs build, preserving the deployed paths, schemas, and provider grouping. Test requests only against a safe, read-only environment and use a key with the intended entitlement.

Provider reads return a `{data, meta}` envelope with `meta.request_id`.
The `data` shape depends on the operation: for example, a Hacker News item
returns `{item, comments}`, rather than a one-element array. Gateway errors
return `{error: {code, message, request_id}}`, with optional error details.

`GET /fetcher/readyz` is public REST discovery and returns
`{status, checks: {backend_authorizer, redis}, meta: {request_id}}`. Healthy
checks are `reachable` or `not_configured`; an `unreachable` dependency
returns HTTP 503 with status `unhealthy`. Readiness is excluded from the SDK
data methods. Its MCP tool keeps the name `get_fetcher_readyz`.

The same contract carries the two authenticated lifecycle surfaces: `/v1/monitors`, and the Company Changes surface under `/v1/watches`, `/v1/events`, `/v1/entities`, and `/v1/intelligence`. `GET` operations require the `monitors:read` scope and the Watch lifecycle writes (`POST /v1/watches`, `PATCH /v1/watches/{id}`) require `monitors:write`; a request without the required scope returns `403 forbidden_scope` with a request ID. There is no public `DELETE`: archive a Watch with `PATCH /v1/watches/{id}` and `{"status":"archived"}`, which is terminal and only an idempotent replay of itself. Watch topic changes are temporal subscription intervals, so disabling a topic stops future observation while its retained history stays readable. Canonical Events are shared public-web intelligence, while a Watch — its id, cadence, topics, and webhook destination — is private to the organization that created it; an object belonging to another organization returns `404`.