API Reference

Use the interactive reference at /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.