ReplyNodes

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

HostUsed for
https://api.replynodes.comREST API
https://mcp.replynodes.com/mcpMCP server. See MCP
https://md.replynodes.comFree keyless Markdown. See Web context
https://brand.replynodes.comFree 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 pathPurpose
POST /v1/monitorsCreate a monitor asynchronously
GET /v1/monitorsList 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}/changesList monitor changes
GET /v1/monitors/{id}/runsList monitor runs
POST /v1/watchesCreate a Watch
GET /v1/watches, GET /v1/watches/{id}List or retrieve Watches
PATCH /v1/watches/{id}Update a Watch
GET /v1/watches/{id}/eventsList events delivered to a Watch
GET /v1/events, GET /v1/events/{id}List or retrieve events you are entitled to
GET /v1/entities/{domain}/eventsList 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.

On this page