openapi: 3.2.0 info: title: Monocrawl Monitors API version: 0.1.0 description: One key, one envelope, one credit meter across social, search, commerce and web data. contact: name: Monocrawl support url: https://www.monocrawl.com/contact termsOfService: https://www.monocrawl.com/legal/terms-and-conditions servers: - url: https://www.monocrawl.com security: - ApiKeyHeader: [] tags: - name: Monitors paths: /v1/monitors/analytics: get: operationId: monitors_analytics tags: - Monitors summary: Monitoring analytics description: 'Your monitoring at a glance: monitors by state, completed and pending checks, findings, alert delivery, credits used, checks served from cache and time to the first finding. Free — costs 0 credits.' parameters: - name: days in: query required: false schema: type: string example: '30' description: Window, up to 90 days - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/analytics.json title: monitors/analytics data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: window: type: - object - 'null' properties: {} additionalProperties: true monitors: type: - object - 'null' properties: {} additionalProperties: true runs: type: - object - 'null' properties: {} additionalProperties: true findings: type: - object - 'null' properties: {} additionalProperties: true delivery: type: - object - 'null' properties: {} additionalProperties: true suppressed_duplicates: type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - window properties: window: type: - object properties: {} additionalProperties: true - required: - monitors properties: monitors: type: - object properties: {} additionalProperties: true - required: - runs properties: runs: type: - object properties: {} additionalProperties: true - required: - findings properties: findings: type: - object properties: {} additionalProperties: true - required: - delivery properties: delivery: type: - object properties: {} additionalProperties: true - required: - suppressed_duplicates properties: suppressed_duplicates: type: - number x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - window: {} monitors: {} runs: {} findings: {} delivery: {} suppressed_duplicates: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/create: get: operationId: monitors_create tags: - Monitors summary: Create a monitor description: Save a monitor and its schedule. A subject monitor follows a resolved name across platforms and records new findings; a feed monitor records new items from a review or listing endpoint; a change monitor snapshots a page or endpoint. Creating costs the listed credits. Each run reserves its quoted credits before starting; unused reserved credits are refunded. Runs pause if available account funding cannot cover the next check. No monthly monitor cap applies. Costs 1 credit per successful live response. parameters: - name: kind in: query required: false schema: type: string enum: - subject - feed - change example: subject description: 'What kind of monitor: subject (a name, handle, product or topic followed across platforms), feed (new items from one review or listing endpoint) or change (a page or endpoint snapshot, the original monitor). Defaults to subject when query is given, change otherwise. Accepted values: subject, feed, change. Case, spaces, hyphens and underscores are interchangeable.' - name: query in: query required: false schema: type: string example: Monzo description: 'What to watch: a name, product, handle, domain or keyword for a subject monitor; for a feed template, its identifier — a subreddit, a video link, an app id, or for Google Maps reviews a pasted Maps link or a Place id (a link is resolved through one places search, charged once).' - name: entity in: query required: false schema: type: string example: bare description: 'subject: the sense id chosen from a preview or a clarification (bare for the plain name, sense:… for a qualified one)' - name: entity_type in: query required: false schema: type: string enum: - creator_media - developer - brand - company - event - community example: brand description: 'subject: creator_media, developer, brand, company, event or community — guides source routing Accepted values: creator_media, developer, brand, company, event, community. Case, spaces, hyphens and underscores are interchangeable.' - name: purpose in: query required: false schema: type: string example: complaints description: A preset id (brand_mentions, complaints, competitor_activity, switching_intent, purchase_intent, questions, developments, app_reviews, local_reviews, custom) or a short free-text purpose - name: sources in: query required: false schema: type: string example: reddit,x,hackernews description: 'subject: platforms to search, comma-separated; defaults to the preset''s recommendation' - name: exclude in: query required: false schema: type: string example: tiktok description: 'subject: platforms to leave out' - name: relationships in: query required: false schema: type: array items: type: string enum: - independent_audience - editorial_news - official_owned - employee_team - collaborator_partner - fan_clip style: form explode: false example: - independent_audience - editorial_news description: 'subject: which classes of material count as findings (official_owned, employee_team, collaborator_partner, editorial_news, fan_clip, independent_audience). Default: everything except unrelated material. Accepted values (comma-separated): independent_audience, editorial_news, official_owned, employee_team, collaborator_partner, fan_clip. Case, spaces, hyphens and underscores are interchangeable.' - name: filters in: query required: false schema: type: array items: type: string enum: - complaints - switching - buying - bugs_crashes - bugs_glitches - bugs_exploits - bugs_blockers - bugs_performance - requests - questions style: form explode: false example: - complaints description: 'subject: deterministic purpose filters applied to findings: complaints, switching, buying, questions Accepted values (comma-separated): complaints, switching, buying, bugs_crashes, bugs_glitches, bugs_exploits, bugs_blockers, bugs_performance, requests, questions. Case, spaces, hyphens and underscores are interchangeable.' - name: aliases in: query required: false schema: type: string example: '@monzo,Monzo Bank' description: 'subject: other names the subject is known by, comma-separated' - name: max_metered in: query required: false schema: type: string example: '1' description: 'subject: how many metered platforms each run may spend on, 0-2 (default 1)' - name: lookback_days in: query required: false schema: type: string example: '7' description: 'subject: how far back the first run looks (default 7); later runs continue from the last successful run' - name: feed_platform in: query required: false schema: type: string example: app_store description: 'feed: platform of the review or listing endpoint' - name: feed_endpoint in: query required: false schema: type: string example: app-reviews description: 'feed: endpoint id, e.g. app-reviews' - name: feed_params_json in: query required: false schema: type: string example: '{"app_id":"310633997"}' description: 'feed: JSON object of parameters for the endpoint' - name: schedule_minutes in: query required: false schema: type: string example: '1440' description: Minutes between runs. The console offers 60, 360, 1440 and 10080; the API accepts any value from 15 to 43200. - name: monthly_cap_credits in: query required: false schema: type: string example: '' description: Legacy field accepted for compatibility but ignored and returned as null. It does not impose a spending cap. Account balance, quoted run cost and existing account safeguards still apply. - name: delivery_in_app in: query required: false schema: type: string example: 'true' description: Create an in-app notification when a run finds something new (default true) - name: delivery_webhook in: query required: false schema: type: string example: 'true' description: Emit monitor.findings to your signed webhook endpoints (default false) - name: name in: query required: false schema: type: string example: Monzo complaints description: Human label; suggested from the purpose and subject when omitted - name: url in: query required: false schema: type: string example: https://example.com/pricing description: 'change: page to watch. Give this OR platform+endpoint.' - name: platform in: query required: false schema: type: string example: github description: 'change: platform of an API endpoint to watch, e.g. github. Give with endpoint.' - name: endpoint in: query required: false schema: type: string example: repo description: 'change: endpoint id to watch, e.g. repo' - name: params_json in: query required: false schema: type: string example: '{"owner":"vercel","repo":"next.js"}' description: 'change: JSON object of parameters passed to the watched endpoint on every run' - name: output in: query required: false schema: type: string enum: - report - everything example: report description: 'subject and feed: report (each run leads with what changed and why it matters, every line with its receipts; the default for the intelligence templates) or everything (every new post, comment or review, listed; the default for feeds and follow templates) Accepted values: report, everything. Case, spaces, hyphens and underscores are interchangeable.' - name: destinations in: query required: false schema: type: string example: '[{"kind":"endpoint","endpoint_id":"whk_…","cadence":"immediate","min_severity":"notable"},{"kind":"email","cadence":"daily"}]' description: 'JSON array of where alerts go and how often. kind: email (the account address), endpoint (one of your Slack channels, Discord channels or webhooks by endpoint_id; omit endpoint_id for every active endpoint), push (the devices that turned push on). cadence: immediate, daily or weekly. min_severity for immediate: info (every new finding), notable or critical. The monitor page is always included unless delivery_in_app=false. Replaces delivery_email, delivery_webhook and delivery_mode when given.' - name: feeds_json in: query required: false schema: type: string example: '[{"platform":"bluesky","endpoint":"user/posts","params":{"handle":"name.bsky.social"}},{"platform":"youtube","endpoint":"channel/videos","params":{"handle":"name"}}]' description: 'Several feeds at once, as a JSON array of {platform, endpoint, params}. Follow an account reads timelines: x/tweets (handle, metered), bluesky/user/posts (handle), youtube/channel/videos (handle or url). Every feed must be live-proven on this deployment; the review says so per feed.' - name: expected_run_credits in: query required: false schema: type: string example: '2' description: 'Optional quote guard: refuse creation when the resolved per-run price differs. Obtain a quote from monitors/test first.' - name: result_mode in: query required: false schema: type: string example: snapshot description: 'Change/endpoint monitors: snapshot saves each bounded response without AI; changes applies existing comparison rules (default). One request per check, no automatic pagination. Responses above 200 KB are not retained.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: rules in: query required: false schema: type: string example: '{"metric_fields":["/followers"]}' description: Optional change-monitor rules as a JSON object. Use metric_fields with up to 10 published numeric object JSON pointers (for example /followers or /stats/likes), with result_mode=changes. Unknown/nonnumeric paths are rejected before a source call or charge; missing actual values are not zero and the check is refunded. Numeric selection replaces family rules. Or use watch_fields for generic field comparisons. See /docs/monitors#metric-fields. - name: relevance_enabled in: query required: false schema: type: string example: 'true' description: Optional on every monitor. Enable or disable relevance filtering. Enabling requires a nonempty relevance_prompt. - name: relevance_prompt in: query required: false schema: type: string example: Only genuine requests for recommendations; exclude promotions. description: Up to 600 characters describing what should trigger an alert. A nonempty value enables filtering unless explicitly disabled. Empty clears it. - name: exclusions in: query required: false schema: type: string example: sponsored,job opening description: Comma-separated phrases skipped before AI; empty clears. Returned by monitor read tools. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/create.json title: monitors/create data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: Exact source identifier; preserve it as a string. status: type: - string - 'null' description: status name: type: - string - 'null' description: name kind: type: - string - 'null' description: kind created_at: type: - string - 'null' description: created at next_run_at: type: - string - 'null' description: next run at target: type: - object - 'null' properties: platform: type: - string - 'null' description: platform endpoint: type: - string - 'null' description: endpoint additionalProperties: true schedule_minutes: type: - number - 'null' description: Configured check interval in minutes. estimated_credits_per_run: type: - number - 'null' description: Current estimate, not a guarantee. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: Exact source identifier; preserve it as a string. minLength: 1 - required: - name properties: name: type: - string description: name minLength: 1 - required: - created_at properties: created_at: type: - string description: created at minLength: 1 - required: - next_run_at properties: next_run_at: type: - string description: next run at minLength: 1 - required: - target properties: target: type: - object properties: platform: type: - string - 'null' description: platform endpoint: type: - string - 'null' description: endpoint additionalProperties: true - required: - schedule_minutes properties: schedule_minutes: type: - number description: Configured check interval in minutes. - required: - estimated_credits_per_run properties: estimated_credits_per_run: type: - number description: Current estimate, not a guarantee. x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: monitor_example status: active default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/delete: delete: operationId: monitors_delete tags: - Monitors summary: Delete a monitor description: 'Permanently delete one of your monitors and its recorded run history, and cancel any check already queued for it. A Monocrawl extra: the reference catalogue catalogue has no monitor delete call, which makes its per-account monitor limit unrecoverable. This cannot be undone. Free — costs 0 credits.' parameters: - name: id in: query required: true schema: type: string example: mon_0f2c8b1d4e6a7c9b0d1e2f3a description: Monitor id - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: confirm in: query required: true schema: type: string example: 'true' description: Set to true to permanently delete this monitor. Send an HTTP DELETE request; GET never deletes. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/delete.json title: monitors/delete data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: id name: type: - string - 'null' description: name runs_deleted: type: - string - 'null' description: runs deleted deleted: type: - boolean - 'null' cancelled_checks: type: - array - 'null' items: type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: id minLength: 1 - required: - name properties: name: type: - string description: name minLength: 1 - required: - runs_deleted properties: runs_deleted: type: - string description: runs deleted minLength: 1 - required: - deleted properties: deleted: type: - boolean - required: - cancelled_checks properties: cancelled_checks: type: - array items: type: - string - 'null' x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: null name: null runs_deleted: null deleted: false cancelled_checks: [] default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/drafts: get: operationId: monitors_drafts tags: - Monitors summary: Monitor drafts description: The proposals waiting for review. A draft is saved, edited, tested and finally activated into a monitor or discarded; nothing runs or is charged while it is a draft. Free — costs 0 credits. parameters: - name: draft_id in: query required: false schema: type: string example: drf_… description: One draft; without it, every open draft - name: proposal_json in: query required: false schema: type: string example: '{…}' description: 'With draft_id: replace the proposal (edited in the review)' - name: activate in: query required: false schema: type: string example: 'true' description: 'With draft_id: create the monitor from the proposal and close the draft' - name: discard in: query required: false schema: type: string example: 'true' description: 'With draft_id: close the draft without creating anything' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/drafts.json title: monitors/drafts data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' status: type: - string - 'null' proposal: type: - object - 'null' properties: {} additionalProperties: true items: type: - array - 'null' items: type: object properties: {} additionalProperties: true minProperties: 1 count: type: - number - 'null' additionalProperties: true anyOf: - required: - items properties: items: type: - array items: type: object properties: {} additionalProperties: true minProperties: 1 - required: - id properties: id: type: - string minLength: 1 x-contract-version: '2026-09-22' examples: - id: null status: null proposal: {} items: [] count: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/export: get: operationId: monitors_export tags: - Monitors summary: Export the evidence description: Every finding in the window with its receipts — source, quote, link, author, posted time, severity, matches, story, topic, your verdict and the raw evidence row it was made from — as CSV or JSON. Free — costs 0 credits. parameters: - name: id in: query required: true schema: type: string example: mon_… description: Monitor id - name: format in: query required: false schema: type: string enum: - csv - json example: csv description: 'csv (default) or json Accepted values: csv, json. Case, spaces, hyphens and underscores are interchangeable.' - name: days in: query required: false schema: type: string example: '30' description: Window, up to 365 days - name: feedback in: query required: false schema: type: string enum: - known - resolved - irrelevant - useful example: useful description: 'Only findings with this verdict Accepted values: known, resolved, irrelevant, useful. Case, spaces, hyphens and underscores are interchangeable.' - name: scope in: query required: false schema: type: string enum: - findings - collected example: collected description: 'findings (default): the retained findings of the window. collected: every item one run collected, retained or not, with the decision and the reason; needs run_id, or takes the latest run. Runs before 5 September 2026 did not keep their collected items and say so. Accepted values: findings, collected. Case, spaces, hyphens and underscores are interchangeable.' - name: run_id in: query required: false schema: type: string example: '1396' description: 'With scope=collected: the run to export. Defaults to the latest run.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/export.json title: monitors/export data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: format: type: - string - 'null' description: format filename: type: - string - 'null' description: filename content_type: type: - string - 'null' description: content type body: type: - string - 'null' description: body rows: type: - number - 'null' truncated: type: - boolean - 'null' additionalProperties: true allOf: - anyOf: - required: - format properties: format: type: - string description: format minLength: 1 - required: - filename properties: filename: type: - string description: filename minLength: 1 - required: - content_type properties: content_type: type: - string description: content type minLength: 1 - required: - body properties: body: type: - string description: body minLength: 1 - required: - rows properties: rows: type: - number - required: - truncated properties: truncated: type: - boolean x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - format: null filename: null content_type: null body: null rows: 0 truncated: false default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/feedback: get: operationId: monitors_feedback tags: - Monitors summary: Mark findings known, resolved, irrelevant or useful description: 'Records your verdict on findings and remembers it: what you mark known, resolved or irrelevant is not surfaced again by later runs (the same conversation, link, wording, topic or, for irrelevant, author), and what you mark useful is kept as a positive example for the relevance filter. Free — costs 0 credits.' parameters: - name: id in: query required: true schema: type: string example: mon_… description: Monitor id - name: ids in: query required: true schema: type: string example: fnd_…,fnd_… description: Finding ids, comma-separated - name: verdict in: query required: true schema: type: string enum: - known - resolved - irrelevant - useful example: irrelevant description: 'known, resolved, irrelevant or useful Accepted values: known, resolved, irrelevant, useful. Case, spaces, hyphens and underscores are interchangeable.' - name: scope in: query required: false schema: type: string enum: - finding - story example: story description: 'finding (default) or story: apply to the whole story the findings belong to Accepted values: finding, story. Case, spaces, hyphens and underscores are interchangeable.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/feedback.json title: monitors/feedback data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: monitor_id: type: - string - 'null' verdict: type: - string - 'null' marked: type: - number - 'null' remembered: type: - number - 'null' stories_muted: type: - number - 'null' note: type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - monitor_id properties: monitor_id: type: - string minLength: 1 - required: - verdict properties: verdict: type: - string minLength: 1 - required: - marked properties: marked: type: - number - required: - remembered properties: remembered: type: - number - required: - stories_muted properties: stories_muted: type: - number - required: - note properties: note: type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - monitor_id: null verdict: null marked: 0 remembered: 0 stories_muted: 0 note: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/findings: get: operationId: monitors_findings tags: - Monitors summary: List monitor findings description: 'The findings a subject or feed monitor has recorded, newest first: each with its platform, author, link, posted time, relationship to the subject and the purpose filters it matched. A finding is recorded once per monitor, however many runs see it. Free — costs 0 credits.' parameters: - name: id in: query required: true schema: type: string example: mon_0f2c8b1d4e6a7c9b0d1e2f3a description: Monitor id - name: unseen in: query required: false schema: type: string example: 'true' description: Only findings not yet marked as seen - name: run_id in: query required: false schema: type: string example: '42' description: Only findings first recorded by this run - name: limit in: query required: false schema: type: string example: '50' description: Page size, 1-200 (default 50) - name: cursor in: query required: false schema: type: string example: '' description: Opaque cursor from the previous page - name: mark_seen in: query required: false schema: type: string example: 'true' description: Mark the returned findings as seen - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/findings.json title: monitors/findings data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: - array items: type: object properties: id: type: - string - 'null' description: id monitor_id: type: - string - 'null' description: monitor id kind: type: - string - 'null' description: kind title: type: - string - 'null' description: title text: type: - string - 'null' description: text url: type: - string - 'null' description: url platform: type: - string - 'null' description: platform first_seen_at: type: - string - 'null' description: first seen at last_seen_at: type: - string - 'null' description: last seen at seen_at: type: - string - 'null' description: seen at feedback: type: - string - 'null' description: feedback data: description: Operation-specific JSON value; inspect the status and requested operation before reading it. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: id minLength: 1 - required: - monitor_id properties: monitor_id: type: - string description: monitor id minLength: 1 - required: - title properties: title: type: - string description: title minLength: 1 - required: - text properties: text: type: - string description: text minLength: 1 - required: - url properties: url: type: - string description: url minLength: 1 - required: - first_seen_at properties: first_seen_at: type: - string description: first seen at minLength: 1 - required: - last_seen_at properties: last_seen_at: type: - string description: last seen at minLength: 1 - required: - seen_at properties: seen_at: type: - string description: seen at minLength: 1 - required: - feedback properties: feedback: type: - string description: feedback minLength: 1 - required: - data properties: data: description: Operation-specific JSON value; inspect the status and requested operation before reading it. count: type: - number - 'null' cursor: type: - string - 'null' has_more: type: - boolean - 'null' unseen: type: - number - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: [] count: 0 cursor: null has_more: false unseen: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/get: get: operationId: monitors_get tags: - Monitors summary: Get a monitor description: One monitor with its target, schedule and the summary of its most recent run. Free — costs 0 credits. parameters: - name: id in: query required: true schema: type: string example: mon_0f2c8b1d4e6a7c9b0d1e2f3a description: Monitor id - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/get.json title: monitors/get data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: id kind: type: - string - 'null' description: kind name: type: - string - 'null' description: name description: type: - string - 'null' description: description status: type: - string - 'null' description: status workflow: type: - string - 'null' description: workflow capped_reason: type: - string - 'null' description: capped reason target_label: type: - string - 'null' description: target label group_id: type: - string - 'null' description: group id last_run_at: type: - string - 'null' description: last run at last_success_at: type: - string - 'null' description: last success at next_run_at: type: - string - 'null' description: next run at created_at: type: - string - 'null' description: created at schedule_minutes: type: - number - 'null' description: schedule minutes estimated_credits_per_run: type: - number - 'null' description: estimated credits per run monthly_cap_credits: type: - number - 'null' description: monthly cap credits credits_spent_month: type: - number - 'null' description: credits spent month consecutive_failures: type: - number - 'null' description: consecutive failures target: type: - object - 'null' properties: {} additionalProperties: true subject: type: - object - 'null' properties: {} additionalProperties: true delivery: type: - object - 'null' properties: {} additionalProperties: true last_run: type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: id minLength: 1 - required: - name properties: name: type: - string description: name minLength: 1 - required: - description properties: description: type: - string description: description minLength: 1 - required: - workflow properties: workflow: type: - string description: workflow minLength: 1 - required: - capped_reason properties: capped_reason: type: - string description: capped reason minLength: 1 - required: - target_label properties: target_label: type: - string description: target label minLength: 1 - required: - group_id properties: group_id: type: - string description: group id minLength: 1 - required: - last_run_at properties: last_run_at: type: - string description: last run at minLength: 1 - required: - last_success_at properties: last_success_at: type: - string description: last success at minLength: 1 - required: - next_run_at properties: next_run_at: type: - string description: next run at minLength: 1 - required: - created_at properties: created_at: type: - string description: created at minLength: 1 - required: - schedule_minutes properties: schedule_minutes: type: - number description: schedule minutes - required: - estimated_credits_per_run properties: estimated_credits_per_run: type: - number description: estimated credits per run - required: - monthly_cap_credits properties: monthly_cap_credits: type: - number description: monthly cap credits - required: - credits_spent_month properties: credits_spent_month: type: - number description: credits spent month - required: - consecutive_failures properties: consecutive_failures: type: - number description: consecutive failures - required: - target properties: target: type: - object properties: {} additionalProperties: true - required: - subject properties: subject: type: - object properties: {} additionalProperties: true - required: - delivery properties: delivery: type: - object properties: {} additionalProperties: true - required: - last_run properties: last_run: type: - object properties: {} additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: null kind: null name: null description: null status: null workflow: null capped_reason: null target_label: null group_id: null last_run_at: null last_success_at: null next_run_at: null created_at: null schedule_minutes: 0 estimated_credits_per_run: 0 monthly_cap_credits: 0 credits_spent_month: 0 consecutive_failures: 0 target: {} subject: {} delivery: {} last_run: {} default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/health: get: operationId: monitors_health tags: - Monitors summary: Monitor health description: 'A monitor''s health and coverage: recent successful and failed checks, missed checks, stale sources, available coverage, delivery status and checks served from cache. Free — costs 0 credits.' parameters: - name: id in: query required: true schema: type: string example: mon_… description: Monitor id - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/health.json title: monitors/health data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: monitor_id: type: - string - 'null' description: monitor id state: type: - string - 'null' description: state window: type: - object - 'null' properties: {} additionalProperties: true runs: type: - object - 'null' properties: {} additionalProperties: true sources: type: - array - 'null' items: type: - object - 'null' properties: {} additionalProperties: true delivery: type: - object - 'null' properties: {} additionalProperties: true attention: description: Operation-specific JSON value; inspect the status and requested operation before reading it. additionalProperties: true allOf: - anyOf: - required: - monitor_id properties: monitor_id: type: - string description: monitor id minLength: 1 - required: - state properties: state: type: - string description: state minLength: 1 - required: - window properties: window: type: - object properties: {} additionalProperties: true - required: - runs properties: runs: type: - object properties: {} additionalProperties: true - required: - sources properties: sources: type: - array items: type: - object - 'null' properties: {} additionalProperties: true - required: - delivery properties: delivery: type: - object properties: {} additionalProperties: true - required: - attention properties: attention: description: Operation-specific JSON value; inspect the status and requested operation before reading it. x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - monitor_id: null state: null window: {} runs: {} sources: [] delivery: {} attention: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors: get: operationId: monitors_index tags: - Monitors summary: List monitors description: Your monitors, newest first, with each one's schedule and next due time. Free — costs 0 credits. parameters: - name: status in: query required: false schema: type: string enum: - active - paused - capped example: active description: 'Filter by monitor status: active or paused Accepted values: active, paused, capped. Case, spaces, hyphens and underscores are interchangeable.' - name: cursor in: query required: false schema: type: string example: '' description: Opaque cursor from the previous page - name: limit in: query required: false schema: type: string example: '25' description: Page size, 1-100 (default 25) - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/index.json title: monitors/index data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: - array items: type: object properties: id: type: - string - 'null' description: id kind: type: - string - 'null' description: kind name: type: - string - 'null' description: name description: type: - string - 'null' description: description status: type: - string - 'null' description: status workflow: type: - string - 'null' description: workflow capped_reason: type: - string - 'null' description: capped reason target_label: type: - string - 'null' description: target label group_id: type: - string - 'null' description: group id last_run_at: type: - string - 'null' description: last run at last_success_at: type: - string - 'null' description: last success at next_run_at: type: - string - 'null' description: next run at created_at: type: - string - 'null' description: created at schedule_minutes: type: - number - 'null' description: schedule minutes estimated_credits_per_run: type: - number - 'null' description: estimated credits per run monthly_cap_credits: type: - number - 'null' description: monthly cap credits credits_spent_month: type: - number - 'null' description: credits spent month consecutive_failures: type: - number - 'null' description: consecutive failures target: type: - object - 'null' properties: {} additionalProperties: true subject: type: - object - 'null' properties: {} additionalProperties: true delivery: type: - object - 'null' properties: {} additionalProperties: true last_run: type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: id minLength: 1 - required: - name properties: name: type: - string description: name minLength: 1 - required: - description properties: description: type: - string description: description minLength: 1 - required: - workflow properties: workflow: type: - string description: workflow minLength: 1 - required: - capped_reason properties: capped_reason: type: - string description: capped reason minLength: 1 - required: - target_label properties: target_label: type: - string description: target label minLength: 1 - required: - group_id properties: group_id: type: - string description: group id minLength: 1 - required: - last_run_at properties: last_run_at: type: - string description: last run at minLength: 1 - required: - last_success_at properties: last_success_at: type: - string description: last success at minLength: 1 - required: - next_run_at properties: next_run_at: type: - string description: next run at minLength: 1 - required: - created_at properties: created_at: type: - string description: created at minLength: 1 - required: - schedule_minutes properties: schedule_minutes: type: - number description: schedule minutes - required: - estimated_credits_per_run properties: estimated_credits_per_run: type: - number description: estimated credits per run - required: - monthly_cap_credits properties: monthly_cap_credits: type: - number description: monthly cap credits - required: - credits_spent_month properties: credits_spent_month: type: - number description: credits spent month - required: - consecutive_failures properties: consecutive_failures: type: - number description: consecutive failures - required: - target properties: target: type: - object properties: {} additionalProperties: true - required: - subject properties: subject: type: - object properties: {} additionalProperties: true - required: - delivery properties: delivery: type: - object properties: {} additionalProperties: true - required: - last_run properties: last_run: type: - object properties: {} additionalProperties: true count: type: - number - 'null' cursor: type: - string - 'null' has_more: type: - boolean - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: [] count: 0 cursor: null has_more: false default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true x-response-schema: https://www.monocrawl.com/schemas/monitors/index.json /v1/monitors/preview: get: operationId: monitors_preview tags: - Monitors summary: Preview a monitor description: 'What a subject monitor would do, before it exists: the resolved subject or the senses to choose from, the recommended platforms with reasons, the schedule, the credit estimate from the price list, and a few pieces of no-cost evidence. Runs the free first pass only — no metered platform and no paid fallback is touched. Free — costs 0 credits.' parameters: - name: query in: query required: true schema: type: string example: Monzo description: The name, handle, URL, domain, product or keyword to follow - name: entity in: query required: false schema: type: string example: bare description: A sense id from an earlier preview, when the name was ambiguous - name: entity_type in: query required: false schema: type: string example: brand description: Optional type hint - name: purpose in: query required: false schema: type: string example: complaints description: Preset id or free text; sets the recommended sources and filters - name: sources in: query required: false schema: type: string example: reddit,x description: Override the recommended platforms - name: schedule_minutes in: query required: false schema: type: string example: '1440' description: Interval used for the monthly estimate - name: monthly_cap_credits in: query required: false schema: type: string example: '' description: Legacy field accepted for compatibility but ignored and returned as null. It does not impose a spending cap. Account balance, quoted run cost and existing account safeguards still apply. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: rules in: query required: false schema: type: string example: '{"metric_fields":["/followers"]}' description: Optional change-monitor rules as a JSON object. Use metric_fields with up to 10 published numeric object JSON pointers (for example /followers or /stats/likes), with result_mode=changes. Unknown/nonnumeric paths are rejected before a source call or charge; missing actual values are not zero and the check is refunded. Numeric selection replaces family rules. Or use watch_fields for generic field comparisons. See /docs/monitors#metric-fields. - name: relevance_enabled in: query required: false schema: type: string example: 'true' description: Optional on every monitor. Enable or disable relevance filtering. Enabling requires a nonempty relevance_prompt. - name: relevance_prompt in: query required: false schema: type: string example: Only genuine requests for recommendations; exclude promotions. description: Up to 600 characters describing what should trigger an alert. A nonempty value enables filtering unless explicitly disabled. Empty clears it. - name: exclusions in: query required: false schema: type: string example: sponsored,job opening description: Comma-separated phrases skipped before AI; empty clears. Returned by monitor read tools. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/preview.json title: monitors/preview data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: kind: type: - string - 'null' description: kind purpose: type: - string - 'null' description: purpose preset: type: - string - 'null' description: preset name: type: - string - 'null' description: name note: type: - string - 'null' description: note schedule_minutes: type: - number - 'null' description: schedule minutes monthly_cap_credits: type: - number - 'null' description: monthly cap credits can_activate: type: - boolean - 'null' description: can activate requires_choice: type: - boolean - 'null' description: requires choice sample: type: - boolean - 'null' description: sample subject: type: - object - 'null' properties: {} additionalProperties: true estimate: type: - object - 'null' properties: {} additionalProperties: true availability: type: - object - 'null' properties: {} additionalProperties: true resolution: type: - object - 'null' properties: {} additionalProperties: true evidence: type: - array - 'null' items: type: - object - 'null' properties: {} additionalProperties: true feeds: type: - array - 'null' items: type: - object - 'null' properties: platform: type: - string - 'null' description: platform label: type: - string - 'null' description: label endpoint: type: - string - 'null' description: endpoint additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - purpose properties: purpose: type: - string description: purpose minLength: 1 - required: - preset properties: preset: type: - string description: preset minLength: 1 - required: - name properties: name: type: - string description: name minLength: 1 - required: - note properties: note: type: - string description: note minLength: 1 - required: - schedule_minutes properties: schedule_minutes: type: - number description: schedule minutes - required: - monthly_cap_credits properties: monthly_cap_credits: type: - number description: monthly cap credits - required: - can_activate properties: can_activate: type: - boolean description: can activate - required: - requires_choice properties: requires_choice: type: - boolean description: requires choice - required: - sample properties: sample: type: - boolean description: sample - required: - subject properties: subject: type: - object properties: {} additionalProperties: true - required: - estimate properties: estimate: type: - object properties: {} additionalProperties: true - required: - availability properties: availability: type: - object properties: {} additionalProperties: true - required: - resolution properties: resolution: type: - object properties: {} additionalProperties: true - required: - evidence properties: evidence: type: - array items: type: - object - 'null' properties: {} additionalProperties: true - required: - feeds properties: feeds: type: - array items: type: - object - 'null' properties: platform: type: - string - 'null' description: platform label: type: - string - 'null' description: label endpoint: type: - string - 'null' description: endpoint additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - kind: null purpose: null preset: null name: null note: null schedule_minutes: 0 monthly_cap_credits: 0 can_activate: false requires_choice: false sample: false subject: {} estimate: {} availability: {} resolution: {} evidence: [] feeds: [] default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/propose: get: operationId: monitors_propose tags: - Monitors summary: Propose a monitor from plain English description: 'Turns a plain-English request into a complete, editable monitor proposal: what it watches, the identifiers it found, the platforms, the matching rules and exclusions, the frequency, the delivery and the estimated cost, with the reason for each choice. Nothing is created. Free — costs 0 credits.' parameters: - name: text in: query required: true schema: type: string example: Tell me when people complain about Monzo on Reddit or Hacker News description: What you want to keep an eye on, in a sentence - name: template in: query required: false schema: type: string example: complaints description: Start from a template id instead of, or as well as, the sentence - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/propose.json title: monitors/propose data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: proposal: type: - object - 'null' properties: {} additionalProperties: true notes: type: - array - 'null' items: type: - string - 'null' requires_choice: type: - boolean - 'null' choices: type: - array - 'null' items: type: - object - 'null' properties: {} additionalProperties: true question: type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - proposal properties: proposal: type: - object properties: {} additionalProperties: true - required: - notes properties: notes: type: - array items: type: - string - 'null' - required: - requires_choice properties: requires_choice: type: - boolean - required: - choices properties: choices: type: - array items: type: - object - 'null' properties: {} additionalProperties: true - required: - question properties: question: type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - proposal: {} notes: [] requires_choice: false choices: [] question: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/report: get: operationId: monitors_report tags: - Monitors summary: Save findings as a report description: Turns a monitor's findings (or one story) into a saved research report with citations, verified facts kept apart from generated interpretation, ready to share or export as Markdown or JSON. Free — costs 0 credits. parameters: - name: id in: query required: true schema: type: string example: mon_… description: Monitor id - name: story_id in: query required: false schema: type: string example: sty_… description: Only this story's findings - name: days in: query required: false schema: type: string example: '7' description: Findings from the last N days (default 7) - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/report.json title: monitors/report data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: report_id: type: - string - 'null' url: type: - string - 'null' findings: type: - number - 'null' stories: type: - number - 'null' additionalProperties: true allOf: - anyOf: - required: - report_id properties: report_id: type: - string minLength: 1 - required: - url properties: url: type: - string minLength: 1 - required: - findings properties: findings: type: - number - required: - stories properties: stories: type: - number x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - report_id: null url: null findings: 0 stories: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/run: get: operationId: monitors_run tags: - Monitors summary: Run a monitor now description: Queue one monitor check outside its schedule. Review the estimate before confirming. The run reserves its quoted credits, settles the actual charge within that quote and refunds unused credits. If available account funding cannot cover the estimate, no job is started and no credits are charged. No monthly monitor cap applies. Free — costs 0 credits. parameters: - name: id in: query required: true schema: type: string example: mon_0f2c8b1d4e6a7c9b0d1e2f3a description: Monitor id - name: confirm in: query required: false schema: type: string example: 'true' description: Without confirm=true the call only returns what a run would cost. With it, the run is charged and queued. - name: expected_run_credits in: query required: false schema: type: string example: '2' description: Refuse a confirmed manual check if its quote changed, including under the reservation lock. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/run.json title: monitors/run data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: id job_id: type: - string - 'null' description: job id reason: type: - string - 'null' description: reason message: type: - string - 'null' description: message next_run_at: type: - string - 'null' description: next run at needs_confirmation: type: - boolean - 'null' description: needs confirmation available: type: - boolean - 'null' description: available enqueued: type: - boolean - 'null' description: enqueued charged: type: - number - 'null' estimate: type: - object - 'null' properties: credits: type: - number - 'null' note: type: - string - 'null' additionalProperties: true cap: type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: id minLength: 1 - required: - job_id properties: job_id: type: - string description: job id minLength: 1 - required: - reason properties: reason: type: - string description: reason minLength: 1 - required: - message properties: message: type: - string description: message minLength: 1 - required: - next_run_at properties: next_run_at: type: - string description: next run at minLength: 1 - required: - needs_confirmation properties: needs_confirmation: type: - boolean description: needs confirmation - required: - available properties: available: type: - boolean description: available - required: - enqueued properties: enqueued: type: - boolean description: enqueued - required: - charged properties: charged: type: - number - required: - estimate properties: estimate: type: - object properties: credits: type: - number - 'null' note: type: - string - 'null' additionalProperties: true - required: - cap properties: cap: type: - object properties: {} additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: null job_id: null reason: null message: null next_run_at: null needs_confirmation: false available: false enqueued: false charged: 0 estimate: credits: 0 note: null cap: {} default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/runs: get: operationId: monitors_runs tags: - Monitors summary: List monitor runs description: The check history for a monitor, newest first, with what changed on each run. Free — costs 0 credits. parameters: - name: id in: query required: true schema: type: string example: mon_0f2c8b1d4e6a7c9b0d1e2f3a description: Monitor id - name: status in: query required: false schema: type: string enum: - ok - error example: ok description: 'Filter by run status: ok or error Accepted values: ok, error. Case, spaces, hyphens and underscores are interchangeable.' - name: from in: query required: false schema: type: string example: '2026-01-01T00:00:00Z' description: Only runs at or after this ISO-8601 time - name: to in: query required: false schema: type: string example: '2026-02-01T00:00:00Z' description: Only runs at or before this ISO-8601 time - name: include in: query required: false schema: type: string example: snapshot,diff description: 'Add the heavy fields: snapshot and/or diff (omitted by default)' - name: cursor in: query required: false schema: type: string example: '' description: Opaque cursor from the previous page - name: limit in: query required: false schema: type: string example: '25' description: Page size, 1-100 (default 25) - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/runs.json title: monitors/runs data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: items: type: - array items: type: object properties: id: type: - string - 'null' description: id monitor_id: type: - string - 'null' description: monitor id run_at: type: - string - 'null' description: run at status: type: - string - 'null' description: status error: type: - string - 'null' description: error processing_status: type: - string - 'null' description: processing status summary: description: Operation-specific JSON value; inspect the status and requested operation before reading it. changed: type: - boolean - 'null' metrics: type: - object - 'null' properties: {} additionalProperties: true credits_charged: type: - number - 'null' description: credits charged credits_refunded: type: - number - 'null' description: credits refunded snapshot: description: Operation-specific JSON value; inspect the status and requested operation before reading it. diff: description: Operation-specific JSON value; inspect the status and requested operation before reading it. additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: id minLength: 1 - required: - monitor_id properties: monitor_id: type: - string description: monitor id minLength: 1 - required: - run_at properties: run_at: type: - string description: run at minLength: 1 - required: - error properties: error: type: - string description: error minLength: 1 - required: - processing_status properties: processing_status: type: - string description: processing status minLength: 1 - required: - summary properties: summary: description: Operation-specific JSON value; inspect the status and requested operation before reading it. - required: - changed properties: changed: type: - boolean - required: - metrics properties: metrics: type: - object properties: {} additionalProperties: true - required: - credits_charged properties: credits_charged: type: - number description: credits charged - required: - credits_refunded properties: credits_refunded: type: - number description: credits refunded - required: - snapshot properties: snapshot: description: Operation-specific JSON value; inspect the status and requested operation before reading it. - required: - diff properties: diff: description: Operation-specific JSON value; inspect the status and requested operation before reading it. count: type: - number - 'null' cursor: type: - string - 'null' has_more: type: - boolean - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - items: [] count: 0 cursor: null has_more: false default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/settings: get: operationId: monitors_settings tags: - Monitors summary: Monitoring settings description: Read or change the monitoring digest schedule and delivery preferences. Reads with no parameters; writes with any supported setting. The legacy monthly_budget_credits field is ignored; account billing limits still apply. Free — costs 0 credits. parameters: - name: monthly_budget_credits in: query required: false schema: type: string description: Deprecated and ignored. No monthly monitor or account monitoring cap is enforced. Runs require sufficient available account funding; account billing limits still apply. - name: digest_frequency in: query required: false schema: type: string enum: - 'off' - daily - weekly example: daily description: 'off, daily or weekly Accepted values: off, daily, weekly. Case, spaces, hyphens and underscores are interchangeable.' - name: digest_hour in: query required: false schema: type: string example: '8' description: UTC hour the digest is assembled - name: digest_email in: query required: false schema: type: string example: 'true' description: Send the digest by email - name: digest_webhook in: query required: false schema: type: string example: 'false' description: Send the digest to subscribed webhooks - name: digest_report in: query required: false schema: type: string example: 'false' description: Also save each digest as a research report - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/settings.json title: monitors/settings data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: digest_frequency: type: - string - 'null' description: digest frequency updated_at: type: - string - 'null' description: updated at digest_hour: type: - number - 'null' monthly_budget_credits: type: 'null' digest_email: type: - boolean - 'null' description: digest email digest_webhook: type: - boolean - 'null' description: digest webhook digest_report: type: - boolean - 'null' description: digest report additionalProperties: true allOf: - anyOf: - required: - digest_frequency properties: digest_frequency: type: - string description: digest frequency minLength: 1 - required: - updated_at properties: updated_at: type: - string description: updated at minLength: 1 - required: - digest_hour properties: digest_hour: type: - number - required: - monthly_budget_credits properties: monthly_budget_credits: type: 'null' - required: - digest_email properties: digest_email: type: - boolean description: digest email - required: - digest_webhook properties: digest_webhook: type: - boolean description: digest webhook - required: - digest_report properties: digest_report: type: - boolean description: digest report x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - digest_frequency: null updated_at: null digest_hour: 0 monthly_budget_credits: null digest_email: false digest_webhook: false digest_report: false default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/stories: get: operationId: monitors_stories tags: - Monitors summary: Monitor stories description: The developing stories a monitor's related findings have been grouped into, with counts, severity and when each was last seen. Free — costs 0 credits. parameters: - name: id in: query required: true schema: type: string example: mon_… description: Monitor id - name: limit in: query required: false schema: type: string example: '20' description: Stories, newest first - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/stories.json title: monitors/stories data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: monitor_id: type: - string - 'null' items: type: - array items: type: object properties: id: type: - string - 'null' description: id monitor_id: type: - string - 'null' description: monitor id key: type: - string - 'null' description: key title: type: - string - 'null' description: title severity: type: - string - 'null' description: severity status: type: - string - 'null' description: status first_seen_at: type: - string - 'null' description: first seen at last_seen_at: type: - string - 'null' description: last seen at last_alerted_at: type: - string - 'null' description: last alerted at findings_count: type: - number - 'null' summary: type: - object - 'null' properties: latest: type: - string - 'null' facts: type: - array - 'null' items: type: - object - 'null' properties: id: type: - string - 'null' description: id at: type: - string - 'null' description: at text: type: - string - 'null' description: text severity: type: - string - 'null' description: severity before: description: Operation-specific JSON value; inspect the status and requested operation before reading it. after: description: Operation-specific JSON value; inspect the status and requested operation before reading it. additionalProperties: true sources: type: - array - 'null' items: type: - string - 'null' additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: id minLength: 1 - required: - monitor_id properties: monitor_id: type: - string description: monitor id minLength: 1 - required: - key properties: key: type: - string description: key minLength: 1 - required: - title properties: title: type: - string description: title minLength: 1 - required: - severity properties: severity: type: - string description: severity minLength: 1 - required: - first_seen_at properties: first_seen_at: type: - string description: first seen at minLength: 1 - required: - last_seen_at properties: last_seen_at: type: - string description: last seen at minLength: 1 - required: - last_alerted_at properties: last_alerted_at: type: - string description: last alerted at minLength: 1 - required: - findings_count properties: findings_count: type: - number - required: - summary properties: summary: type: - object properties: latest: type: - string - 'null' facts: type: - array - 'null' items: type: - object - 'null' properties: id: type: - string - 'null' description: id at: type: - string - 'null' description: at text: type: - string - 'null' description: text severity: type: - string - 'null' description: severity before: description: Operation-specific JSON value; inspect the status and requested operation before reading it. after: description: Operation-specific JSON value; inspect the status and requested operation before reading it. additionalProperties: true sources: type: - array - 'null' items: type: - string - 'null' additionalProperties: true additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - monitor_id: null items: [] default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/test: get: operationId: monitors_test tags: - Monitors summary: Test a monitor now description: Run one real check for a monitor that does not exist yet and see what you would have been told about. Charged like one run and refunded down to what was retrieved; nothing is recorded and nothing is sent. Free — costs 0 credits. parameters: - name: query in: query required: false schema: type: string example: Monzo description: The name, handle, URL, domain, product or keyword the monitor would follow - name: entity in: query required: false schema: type: string example: bare description: A sense id from a preview when the name was ambiguous - name: purpose in: query required: false schema: type: string example: complaints description: Template id or free text - name: sources in: query required: false schema: type: string example: reddit,x description: Platforms to search - name: filters in: query required: false schema: type: array items: type: string enum: - complaints - switching - buying - bugs_crashes - bugs_glitches - bugs_exploits - bugs_blockers - bugs_performance - requests - questions style: form explode: false example: - complaints description: 'Purpose filters Accepted values (comma-separated): complaints, switching, buying, bugs_crashes, bugs_glitches, bugs_exploits, bugs_blockers, bugs_performance, requests, questions. Case, spaces, hyphens and underscores are interchangeable.' - name: confirm in: query required: false schema: type: string example: 'true' description: Without confirm=true the call only returns what the test would cost. With it, the test is charged like one run. - name: endpoint in: query required: false schema: type: string example: profile description: Endpoint identifier within the platform. - name: expected_run_credits in: query required: false schema: type: string example: '2' description: Refuse a confirmed preview if the per-run price changed after quoting. - name: kind in: query required: false schema: type: string example: change description: change for a URL or endpoint request; subject/feed for existing analysis workflows. - name: monthly_cap_credits in: query required: false schema: type: string example: '' description: Legacy field accepted for compatibility but ignored and returned as null. It does not impose a spending cap. Account balance, quoted run cost and existing account safeguards still apply. - name: params_json in: query required: false schema: type: string example: '{"handle":"torvalds"}' description: JSON object of endpoint parameters. Validated against the current registry; no credentials. - name: platform in: query required: false schema: type: string example: github description: Platform for an endpoint request. - name: result_mode in: query required: false schema: type: string enum: - snapshot - changes example: snapshot description: 'snapshot or changes. Neither enables AI on an endpoint request. Accepted values: snapshot, changes. Case, spaces, hyphens and underscores are interchangeable.' - name: schedule_minutes in: query required: false schema: type: string example: '1440' description: Fixed interval in minutes for the proposed monitor. - name: url in: query required: false schema: type: string example: https://example.com description: A page URL instead of platform/endpoint. - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: rules in: query required: false schema: type: string example: '{"metric_fields":["/followers"]}' description: Optional change-monitor rules as a JSON object. Use metric_fields with up to 10 published numeric object JSON pointers (for example /followers or /stats/likes), with result_mode=changes. Unknown/nonnumeric paths are rejected before a source call or charge; missing actual values are not zero and the check is refunded. Numeric selection replaces family rules. Or use watch_fields for generic field comparisons. See /docs/monitors#metric-fields. - name: relevance_enabled in: query required: false schema: type: string example: 'true' description: Optional on every monitor. Enable or disable relevance filtering. Enabling requires a nonempty relevance_prompt. - name: relevance_prompt in: query required: false schema: type: string example: Only genuine requests for recommendations; exclude promotions. description: Up to 600 characters describing what should trigger an alert. A nonempty value enables filtering unless explicitly disabled. Empty clears it. - name: exclusions in: query required: false schema: type: string example: sponsored,job opening description: Comma-separated phrases skipped before AI; empty clears. Returned by monitor read tools. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/test.json title: monitors/test data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: kind: type: - string - 'null' description: kind outcome: type: - string - 'null' description: outcome note: type: - string - 'null' description: note charged: type: - number - 'null' description: charged considered: type: - number - 'null' description: considered needs_confirmation: type: - boolean - 'null' target: type: - object - 'null' properties: {} additionalProperties: true estimate: type: - object - 'null' properties: {} additionalProperties: true resolution: type: - object - 'null' properties: {} additionalProperties: true would_report: type: - array - 'null' items: type: - object - 'null' properties: {} additionalProperties: true sample: type: - object - boolean - 'null' properties: {} additionalProperties: true description: A change-check baseline returns an operation-specific object (page title/length or sampled records). Quotes and subject/feed checks return false; inspect outcome and needs_confirmation. additionalProperties: true allOf: - anyOf: - required: - outcome properties: outcome: type: - string description: outcome minLength: 1 - required: - note properties: note: type: - string description: note minLength: 1 - required: - charged properties: charged: type: - number description: charged - required: - considered properties: considered: type: - number description: considered - required: - needs_confirmation properties: needs_confirmation: type: - boolean - required: - target properties: target: type: - object properties: {} additionalProperties: true - required: - estimate properties: estimate: type: - object properties: {} additionalProperties: true - required: - resolution properties: resolution: type: - object properties: {} additionalProperties: true - required: - would_report properties: would_report: type: - array items: type: - object - 'null' properties: {} additionalProperties: true - required: - sample properties: sample: type: - object - boolean properties: {} additionalProperties: true description: A change-check baseline returns an operation-specific object (page title/length or sampled records). Quotes and subject/feed checks return false; inspect outcome and needs_confirmation. x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - kind: null outcome: null note: null charged: 0 considered: 0 needs_confirmation: false target: {} estimate: {} resolution: {} would_report: [] sample: {} default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/test-delivery: get: operationId: monitors_test_delivery tags: - Monitors summary: Send a sample alert description: 'Sends one clearly-marked sample alert (a short report with receipts) to the destinations given, right now, and reports what each one answered. Nothing is recorded, nothing is charged, and no real finding is involved: it proves the channel works before a monitor is switched on. Free — costs 0 credits.' parameters: - name: destinations in: query required: true schema: type: string example: '[{"kind":"endpoint","endpoint_id":"whk_…"}]' description: The destinations to send the sample to, as for monitors/create - name: name in: query required: false schema: type: string example: Monzo complaints description: The monitor name to show on the sample - name: id in: query required: false schema: type: string example: mon_… description: 'The monitor the sample is sent from, when it already exists: the sample then links to that monitor’s page and takes its name. Without it, the sample links to the monitors list.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/test-delivery.json title: monitors/test-delivery data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: sent: type: - number - 'null' failed: type: - number - 'null' results: type: - array items: type: object properties: destination: type: - string - 'null' kind: type: - string - 'null' ok: type: - boolean - 'null' real: type: - boolean - 'null' detail: type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - destination properties: destination: type: - string minLength: 1 - required: - ok properties: ok: type: - boolean - required: - real properties: real: type: - boolean - required: - detail properties: detail: type: - string minLength: 1 sample: type: - boolean - 'null' note: type: - string - 'null' additionalProperties: true required: - results x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - sent: 0 failed: 0 results: [] sample: false note: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/timeseries: get: operationId: monitors_timeseries tags: - Monitors summary: Monitor metric timeseries description: One numeric metric from a monitor's runs as a chartable time series. Free — costs 0 credits. parameters: - name: id in: query required: true schema: type: string example: mon_0f2c8b1d4e6a7c9b0d1e2f3a description: Monitor id - name: metric in: query required: true schema: type: string example: content_length description: Metric key to chart; a 422 lists the metrics this monitor has recorded - name: from in: query required: false schema: type: string example: '2026-01-01T00:00:00Z' description: Only points at or after this ISO-8601 time - name: to in: query required: false schema: type: string example: '2026-02-01T00:00:00Z' description: Only points at or before this ISO-8601 time - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/timeseries.json title: monitors/timeseries data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: monitor_id: type: - string - 'null' description: monitor id metric: type: - string - 'null' description: metric from: type: - string - 'null' description: from to: type: - string - 'null' description: to count: type: - number - 'null' points: type: - array - 'null' items: type: - object - 'null' properties: t: type: - string - 'null' value: type: - number - 'null' additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - monitor_id properties: monitor_id: type: - string description: monitor id minLength: 1 - required: - metric properties: metric: type: - string description: metric minLength: 1 - required: - from properties: from: type: - string description: from minLength: 1 - required: - to properties: to: type: - string description: to minLength: 1 - required: - points properties: points: type: - array items: type: - object - 'null' properties: t: type: - string - 'null' value: type: - number - 'null' additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - monitor_id: null metric: null from: null to: null count: 0 points: [] default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/trends: get: operationId: monitors_trends tags: - Monitors summary: Monitor trends description: A metric over time with the previous period and the baseline beside it, so a change can be judged against what is normal for this monitor. Free — costs 0 credits. parameters: - name: id in: query required: true schema: type: string example: mon_… description: Monitor id - name: metric in: query required: false schema: type: string example: findings description: findings, or any numeric metric the runs record - name: days in: query required: false schema: type: string example: '30' description: Window, up to 90 days - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/trends.json title: monitors/trends data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: monitor_id: type: - string - 'null' metric: type: - string - 'null' days: type: - number - 'null' points: type: - array - 'null' items: type: - object - 'null' properties: t: type: - string - 'null' value: type: - number - 'null' additionalProperties: true previous_points: type: - array - 'null' items: type: - object - 'null' properties: t: type: - string - 'null' value: type: - number - 'null' additionalProperties: true current: type: - object - 'null' properties: {} additionalProperties: true previous: type: - object - 'null' properties: {} additionalProperties: true comparison: type: - object - 'null' properties: {} additionalProperties: true baseline: description: Operation-specific JSON value; inspect the status and requested operation before reading it. additionalProperties: true allOf: - anyOf: - required: - monitor_id properties: monitor_id: type: - string minLength: 1 - required: - metric properties: metric: type: - string minLength: 1 - required: - days properties: days: type: - number - required: - points properties: points: type: - array items: type: - object - 'null' properties: t: type: - string - 'null' value: type: - number - 'null' additionalProperties: true - required: - previous_points properties: previous_points: type: - array items: type: - object - 'null' properties: t: type: - string - 'null' value: type: - number - 'null' additionalProperties: true - required: - current properties: current: type: - object properties: {} additionalProperties: true - required: - previous properties: previous: type: - object properties: {} additionalProperties: true - required: - comparison properties: comparison: type: - object properties: {} additionalProperties: true - required: - baseline properties: baseline: description: Operation-specific JSON value; inspect the status and requested operation before reading it. x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - monitor_id: null metric: null days: 0 points: [] previous_points: [] current: {} previous: {} comparison: {} baseline: null default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/monitors/update: get: operationId: monitors_update tags: - Monitors summary: Update a monitor description: Pause, resume, rename, reschedule or re-scope one of your monitors. Give at least one field besides id. Free — costs 0 credits. parameters: - name: id in: query required: true schema: type: string example: mon_0f2c8b1d4e6a7c9b0d1e2f3a description: Monitor id - name: status in: query required: false schema: type: string enum: - active - paused example: paused description: 'active to resume runs, paused to stop them. Pausing clears the next run time; resuming schedules the next run one interval from now. Accepted values: active, paused. Case, spaces, hyphens and underscores are interchangeable.' - name: name in: query required: false schema: type: string example: Monzo complaints description: New label; pass an empty string to clear it - name: schedule_minutes in: query required: false schema: type: string example: '1440' description: New interval between runs; minimum 15, maximum 43200. Rescheduling re-times the next run from now. - name: monthly_cap_credits in: query required: false schema: type: string example: '' description: Legacy field accepted for compatibility but ignored and returned as null. It does not impose a spending cap. Account balance, quoted run cost and existing account safeguards still apply. - name: delivery_in_app in: query required: false schema: type: string example: 'true' description: 'subject/feed: in-app notifications on or off' - name: delivery_webhook in: query required: false schema: type: string example: 'false' description: 'subject/feed: signed webhook deliveries on or off' - name: sources in: query required: false schema: type: string example: reddit,hackernews description: 'subject: replace the platforms searched' - name: relationships in: query required: false schema: type: array items: type: string enum: - independent_audience - editorial_news - official_owned - employee_team - collaborator_partner - fan_clip style: form explode: false example: - independent_audience description: 'subject: replace which classes of material count Accepted values (comma-separated): independent_audience, editorial_news, official_owned, employee_team, collaborator_partner, fan_clip. Case, spaces, hyphens and underscores are interchangeable.' - name: filters in: query required: false schema: type: array items: type: string enum: - complaints - switching - buying - bugs_crashes - bugs_glitches - bugs_exploits - bugs_blockers - bugs_performance - requests - questions style: form explode: false example: - complaints description: 'subject: replace the purpose filters Accepted values (comma-separated): complaints, switching, buying, bugs_crashes, bugs_glitches, bugs_exploits, bugs_blockers, bugs_performance, requests, questions. Case, spaces, hyphens and underscores are interchangeable.' - name: max_metered in: query required: false schema: type: string example: '1' description: 'subject: metered platforms per run, 0-2' - name: output in: query required: false schema: type: string example: report description: 'subject and feed: report (each run leads with what changed and why it matters, every line with its receipts; the default for the intelligence templates) or everything (every new post, comment or review, listed; the default for feeds and follow templates)' - name: destinations in: query required: false schema: type: string example: '[{"kind":"endpoint","endpoint_id":"whk_…","cadence":"immediate","min_severity":"notable"},{"kind":"email","cadence":"daily"}]' description: 'JSON array of where alerts go and how often. kind: email (the account address), endpoint (one of your Slack channels, Discord channels or webhooks by endpoint_id; omit endpoint_id for every active endpoint), push (the devices that turned push on). cadence: immediate, daily or weekly. min_severity for immediate: info (every new finding), notable or critical. The monitor page is always included unless delivery_in_app=false. Replaces delivery_email, delivery_webhook and delivery_mode when given.' - name: feeds_json in: query required: false schema: type: string example: '[{"platform":"bluesky","endpoint":"user/posts","params":{"handle":"name.bsky.social"}},{"platform":"youtube","endpoint":"channel/videos","params":{"handle":"name"}}]' description: 'Several feeds at once, as a JSON array of {platform, endpoint, params}. Follow an account reads timelines: x/tweets (handle, metered), bluesky/user/posts (handle), youtube/channel/videos (handle or url). Every feed must be live-proven on this deployment; the review says so per feed.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: rules in: query required: false schema: type: string example: '{"metric_fields":["/followers"]}' description: Optional change-monitor rules as a JSON object. Use metric_fields with up to 10 published numeric object JSON pointers (for example /followers or /stats/likes), with result_mode=changes. Unknown/nonnumeric paths are rejected before a source call or charge; missing actual values are not zero and the check is refunded. Numeric selection replaces family rules. Or use watch_fields for generic field comparisons. See /docs/monitors#metric-fields. - name: relevance_enabled in: query required: false schema: type: string example: 'true' description: Optional on every monitor. Enable or disable relevance filtering. Enabling requires a nonempty relevance_prompt. - name: relevance_prompt in: query required: false schema: type: string example: Only genuine requests for recommendations; exclude promotions. description: Up to 600 characters describing what should trigger an alert. A nonempty value enables filtering unless explicitly disabled. Empty clears it. - name: exclusions in: query required: false schema: type: string example: sponsored,job opening description: Comma-separated phrases skipped before AI; empty clears. Returned by monitor read tools. - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/monitors/update.json title: monitors/update data fields description: Required core structure for successful data, with optional source fields. Additional fields are allowed. This is not a completeness guarantee. type: object properties: id: type: - string - 'null' description: id kind: type: - string - 'null' description: kind name: type: - string - 'null' description: name description: type: - string - 'null' description: description status: type: - string - 'null' description: status workflow: type: - string - 'null' description: workflow capped_reason: type: - string - 'null' description: capped reason target_label: type: - string - 'null' description: target label group_id: type: - string - 'null' description: group id last_run_at: type: - string - 'null' description: last run at last_success_at: type: - string - 'null' description: last success at next_run_at: type: - string - 'null' description: next run at created_at: type: - string - 'null' description: created at schedule_minutes: type: - number - 'null' description: schedule minutes estimated_credits_per_run: type: - number - 'null' description: estimated credits per run monthly_cap_credits: type: - number - 'null' description: monthly cap credits credits_spent_month: type: - number - 'null' description: credits spent month consecutive_failures: type: - number - 'null' description: consecutive failures target: type: - object - 'null' properties: {} additionalProperties: true subject: type: - object - 'null' properties: {} additionalProperties: true delivery: type: - object - 'null' properties: {} additionalProperties: true last_run: type: - object - 'null' properties: {} additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - id properties: id: type: - string description: id minLength: 1 - required: - name properties: name: type: - string description: name minLength: 1 - required: - description properties: description: type: - string description: description minLength: 1 - required: - workflow properties: workflow: type: - string description: workflow minLength: 1 - required: - capped_reason properties: capped_reason: type: - string description: capped reason minLength: 1 - required: - target_label properties: target_label: type: - string description: target label minLength: 1 - required: - group_id properties: group_id: type: - string description: group id minLength: 1 - required: - last_run_at properties: last_run_at: type: - string description: last run at minLength: 1 - required: - last_success_at properties: last_success_at: type: - string description: last success at minLength: 1 - required: - next_run_at properties: next_run_at: type: - string description: next run at minLength: 1 - required: - created_at properties: created_at: type: - string description: created at minLength: 1 - required: - schedule_minutes properties: schedule_minutes: type: - number description: schedule minutes - required: - estimated_credits_per_run properties: estimated_credits_per_run: type: - number description: estimated credits per run - required: - monthly_cap_credits properties: monthly_cap_credits: type: - number description: monthly cap credits - required: - credits_spent_month properties: credits_spent_month: type: - number description: credits spent month - required: - consecutive_failures properties: consecutive_failures: type: - number description: consecutive failures - required: - target properties: target: type: - object properties: {} additionalProperties: true - required: - subject properties: subject: type: - object properties: {} additionalProperties: true - required: - delivery properties: delivery: type: - object properties: {} additionalProperties: true - required: - last_run properties: last_run: type: - object properties: {} additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - id: null kind: null name: null description: null status: null workflow: null capped_reason: null target_label: null group_id: null last_run_at: null last_success_at: null next_run_at: null created_at: null schedule_minutes: 0 estimated_credits_per_run: 0 monthly_cap_credits: 0 credits_spent_month: 0 consecutive_failures: 0 target: {} subject: {} delivery: {} last_run: {} default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 0 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true components: schemas: Error: type: object required: - success - error - credits_used - request_id properties: success: const: false error: type: object required: - type - message - status properties: type: type: string enum: - UNAUTHORIZED - KEY_REVOKED - KEY_LIMIT_EXCEEDED - RATE_LIMITED - INSUFFICIENT_CREDITS - RESOURCE_NOT_FOUND - INVALID_PARAMETERS - TARGET_ACCESS_DENIED - UPSTREAM_ERROR - UPSTREAM_TIMEOUT - FREE_CAPACITY_UNAVAILABLE - CAPACITY_UNAVAILABLE - ENDPOINT_NOT_FOUND - ENDPOINT_NOT_AVAILABLE - FAIR_USE_EXCEEDED - INTERNAL_ERROR message: type: string status: type: integer doc_url: type: string description: Deep link to the exact section of the errors guide for this type. details: type: object credits_used: type: - integer - 'null' description: Confirmed net charge; null when billing is pending reconciliation. Inspect error.details.billing_status and retain request_id. credits_remaining: type: integer request_id: type: string Success: type: object required: - success - platform - endpoint - data - credits_used - credits_remaining - request_id properties: _completeness: type: object description: Reported response completeness, not a guarantee of complete platform history. Missing source assertions remain unknown. properties: state: type: string enum: - complete - partial - unknown scope: type: string inspection_limited: type: boolean success: const: true platform: type: string endpoint: type: string description: The resolved path, e.g. `/v1/github/profile`. data: description: Amazon responses include marketplace.country and marketplace.domain (resolved request marketplace, UK by default). X profiles preserve location, bio_link and cover_url when supplied. TikTok profiles preserve commerce_user, seller, region, location and business_category when supplied; region identifies the account region rather than personal residence. TikTok comments use platform_default selection, which can change between fetches; keep the same video and options when following cursors. Amazon review variant is readable text. Facebook profiles preserve cover_url, following and created_at when supplied; likes_count and followers are distinct and follower totals may be rounded. Endpoint-specific normalized payload, not one universal post/profile schema. Many lists use items/count/cursor; a null cursor means no usable next cursor was supplied, not proof that all history was retrieved. Check has_more and warnings where present. Social full-profile bundles use posts_cursor and posts_pagination.next_params; retain all returned next parameters. YouTube channel bundles instead use recent_videos, cursor and recent_videos_pagination. Inspect complete/partial/legs where supplied for bounded or failed components. Optional model-derived fields are labelled, not source facts. credits_used: type: integer credits_remaining: type: integer request_id: type: string cached: type: boolean stale: type: boolean description: True only for an explicitly labelled, zero-credit reference snapshot served after a temporary upstream failure. age_seconds: type: integer minimum: 0 description: Age of a stale snapshot since its original retrieval; not reset by outage recovery. fetched_at: type: string format: date-time description: Original retrieval time of a stale snapshot, in UTC. synthetic: type: boolean description: Present and true only on the explicitly requested /sandbox surface. Synthetic responses are representative and charged 0 credits; production /v1 never returns them. degraded: type: boolean description: Reserved for sandbox compatibility. Production /v1 reports upstream failure as an error and never serves a representative fallback. securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-api-key description: Your API key (`mn_…`), from the console. The recommended style. BearerKey: type: http scheme: bearer description: The same key as a Bearer token, for clients that only expose an Authorization field. Keys are never accepted in the query string — URLs leak into logs and referrers. x-provenance: method: harvested publisher: Monocrawl source: https://www.monocrawl.com/openapi.json note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)