# API conventions

> Hosts, envelopes, errors, scopes and the monitor and Company Changes operations that apply across the API.

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

# API conventions

The [interactive API reference](https://docs.replynodes.com/reference) lists every operation with its parameters and response schema. It is generated from the runtime capability OpenAPI contract, which is also served as [`/api/openapi.json`](https://docs.replynodes.com/api/openapi.json). This page covers what applies across operations.

If this page and the contract disagree, the OpenAPI contract wins. Requests sent from the interactive reference are real requests that use your key.

## Hosts

| Host | Used for |
| --- | --- |
| `https://api.replynodes.com` | REST API |
| `https://mcp.replynodes.com/mcp` | MCP server. See [MCP](https://docs.replynodes.com/docs/mcp) |
| `https://md.replynodes.com` | Free keyless Markdown. See [Web context](https://docs.replynodes.com/docs/guides/web) |
| `https://brand.replynodes.com` | Free keyless brand kit and logo. See [Brand intelligence](https://docs.replynodes.com/docs/guides/brand-intelligence) |

## Authentication

Send `Authorization: Bearer $REPLYNODES_API_KEY`. See [Authentication](https://docs.replynodes.com/docs/auth) for keys, scopes and OAuth.

## Response envelope

Provider reads return `{ data, meta }`. `meta.request_id` is always present. `meta` can also carry `contract_version`, `generated_at`, `availability`, `detail`, `missing_fields`, `next_cursor` and `stale`.

The shape of `data` depends on the operation. For example, a Hacker News item returns `{ item, comments }` inside `data`, and a search returns an array of records. Open the operation in the [interactive reference](https://docs.replynodes.com/reference) for its exact schema.

Pagination depends on the source. Where an operation exposes a cursor, it is `meta.next_cursor`. Other sources use a `page` number, or a `next_token` for Google Play reviews. Each [guide](https://docs.replynodes.com/docs/guides) says which one applies.

## Errors

Gateway errors return `{ error: { code, message, request_id } }`, with optional fields such as `reason`, `retryable` and `next_action`. The full list of codes, with retry guidance, is on [Errors](https://docs.replynodes.com/docs/production/errors).

## Readiness

`GET /fetcher/readyz` is public and returns `{ status, checks: { backend_authorizer, redis }, meta: { request_id } }`. A healthy check is `reachable` or `not_configured`. An `unreachable` dependency returns HTTP 503 with status `unhealthy`. Readiness is excluded from the SDK data methods, and its MCP tool is named `get_fetcher_readyz`.

## Monitors and Company Changes

Two authenticated surfaces manage resources in your organization:

- **Monitors** watch a page for changes on a schedule.
- **Company Changes** has **Watches** and the public **Events** they observe. A Watch (its id, cadence, topics and webhook destination) is private to the organization that created it. Canonical Events are shared public-web intelligence.

| Method and path | Purpose |
| --- | --- |
| `POST /v1/monitors` | Create a monitor asynchronously |
| `GET /v1/monitors` | List monitors for your organization |
| `GET /v1/monitors/{id}` | Get a monitor |
| `PATCH /v1/monitors/{id}` | Update frequency, pause state or webhook |
| `GET /v1/monitors/{id}/changes` | List monitor changes |
| `GET /v1/monitors/{id}/runs` | List monitor runs |
| `POST /v1/watches` | Create a Watch |
| `GET /v1/watches`, `GET /v1/watches/{id}` | List or retrieve Watches |
| `PATCH /v1/watches/{id}` | Update a Watch |
| `GET /v1/watches/{id}/events` | List events delivered to a Watch |
| `GET /v1/events`, `GET /v1/events/{id}` | List or retrieve events you are entitled to |
| `GET /v1/entities/{domain}/events` | List events for a company domain |
| `GET /v1/entities/{domain}/history/{topic}` | Retrieve topic history for a company domain |
| `GET /v1/intelligence/{domain}` | Retrieve company intelligence |

`GET` operations need the `monitors:read` scope, and writes need `monitors:write`. A request without the required scope returns `403 forbidden_scope` with a request id. See [Authentication](https://docs.replynodes.com/docs/auth#scopes) for how scopes are issued.

There is no public `DELETE`. To remove a Watch, send `PATCH /v1/watches/{id}` with `{"status":"archived"}`. Archiving is terminal, and only an identical repeat of it is accepted. Disabling a topic stops future observation, and its retained history stays readable. An object that belongs to another organization returns `404`.
