API conventions
The interactive API 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. 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://md.replynodes.com | Free keyless Markdown. See Web context |
https://brand.replynodes.com | Free keyless brand kit and logo. See Brand intelligence |
Authentication
Send Authorization: Bearer $REPLYNODES_API_KEY. See Authentication 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 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 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.
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 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.