openapi: 3.2.0 info: title: Monocrawl Content Analysis 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: Content Analysis paths: /v1/content_analysis/categories: get: operationId: content_analysis_categories tags: - Content Analysis summary: Content Analysis categories description: Monocrawl's own mention-classification taxonomy (taxonomy id monocrawl.content_analysis.v1), including the full keyword list behind each category so any classification can be audited. Static, costs no credits. Free — costs 0 credits. parameters: - 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/content_analysis/categories.json title: content_analysis/categories data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' classification: description: Optional classification supplied by this operation. Null means unknown. type: - object - 'null' properties: ai_used: description: Optional ai used supplied by this operation. Null means unknown. type: - boolean - 'null' applied_to: description: Optional applied to supplied by this operation. Null means unknown. type: - string - 'null' method: description: Optional method supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: code: description: Optional code supplied by this operation. Null means unknown. type: - string - 'null' description: description: Source description; null or absent means not supplied. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' term_count: description: Optional term count supplied by this operation. Null means unknown. type: - number - 'null' terms: description: Optional terms supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - code properties: code: description: Optional code supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - description properties: description: description: Source description; null or absent means not supplied. type: - string minLength: 1 - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - term_count properties: term_count: description: Optional term count supplied by this operation. Null means unknown. type: - number - required: - terms properties: terms: description: Optional terms supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' taxonomy: description: Optional taxonomy supplied by this operation. Null means unknown. type: - string - '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: - _warnings: - example classification: ai_used: false applied_to: example method: example count: 0 items: - code: example description: example name: example term_count: 0 terms: - example taxonomy: example 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/content_analysis/filters: get: operationId: content_analysis_filters tags: - Content Analysis summary: Content Analysis filters description: The filterable fields for the content analysis endpoints — field, type, operators, allowed values, which endpoints accept it and whether it is applied upstream or locally. Generated from the adapter's own filter implementation, so it cannot drift. Static, costs no credits. Free — costs 0 credits. parameters: - 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/content_analysis/filters.json title: content_analysis/filters data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: applies_to: description: Optional applies to supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' doc: description: Optional doc supplied by this operation. Null means unknown. type: - string - 'null' example: description: Optional example supplied by this operation. Null means unknown. type: - string - 'null' field: description: Optional field supplied by this operation. Null means unknown. type: - string - 'null' operators: description: Optional operators supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' stage: description: Optional stage supplied by this operation. Null means unknown. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' values: description: Optional values supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - applies_to properties: applies_to: description: Optional applies to supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - doc properties: doc: description: Optional doc supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - example properties: example: description: Optional example supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - field properties: field: description: Optional field supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - operators properties: operators: description: Optional operators supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - stage properties: stage: description: Optional stage supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - values properties: values: description: Optional values supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' stages: description: Optional stages supplied by this operation. Null means unknown. type: - object - 'null' properties: local: description: Optional local supplied by this operation. Null means unknown. type: - string - 'null' upstream: description: Optional upstream supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true syntax: description: Optional syntax supplied by this operation. Null means unknown. type: - string - '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: - _warnings: - example count: 0 items: - applies_to: - example doc: example example: example field: example operators: - example stage: example type: example values: - example stages: local: example upstream: example syntax: example 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/content_analysis/languages: get: operationId: content_analysis_languages tags: - Content Analysis summary: Content Analysis languages description: Reference list of the ISO-639-1 language codes content analysis can genuinely filter on, each marked with which source honours it. Static, costs no credits. Free — costs 0 credits. parameters: - 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/content_analysis/languages.json title: content_analysis/languages data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: code: description: Optional code supplied by this operation. Null means unknown. type: - string - 'null' filterable_via: description: Optional filterable via supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' note: description: Optional note supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - code properties: code: description: Optional code supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - filterable_via properties: filterable_via: description: Optional filterable via supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - note properties: note: description: Optional note supplied by this operation. Null means unknown. type: - string minLength: 1 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: - _warnings: - example count: 0 items: - code: example filterable_via: - example name: example note: example 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/content_analysis/locations: get: operationId: content_analysis_locations tags: - Content Analysis summary: Content Analysis locations description: Reference list of the ISO-3166 alpha-2 country codes content analysis can genuinely filter on — publisher country for news, storefront for rating-distribution. Static, costs no credits. Free — costs 0 credits. parameters: - 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/content_analysis/locations.json title: content_analysis/locations data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: code: description: Optional code supplied by this operation. Null means unknown. type: - string - 'null' filterable_via: description: Optional filterable via supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' note: description: Optional note supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - code properties: code: description: Optional code supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - filterable_via properties: filterable_via: description: Optional filterable via supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - note properties: note: description: Optional note supplied by this operation. Null means unknown. type: - string minLength: 1 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: - _warnings: - example count: 0 items: - code: example filterable_via: - example name: example note: example 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/content_analysis/phrase-trends: get: operationId: content_analysis_phrase_trends tags: - Content Analysis summary: Keyword mention trends description: Mention volume and sentiment for a keyword bucketed by day, week or month across the sources we can reach. Bucket heights are bounded by each source's per-query cap, so the series is a shape, not a census — the response says so explicitly. Costs 5 credits per successful live response. parameters: - name: keyword in: query required: true schema: type: string example: kubernetes description: Phrase to trend - name: date_from in: query required: true schema: type: string example: '2026-08-01' description: ISO-8601 start of the window - name: date_to in: query required: false schema: type: string example: '2026-08-31' description: ISO-8601 end of the window (default now) - name: date_group in: query required: false schema: type: string enum: - day - week - month example: day description: 'day (default), week or month; max 400 buckets Accepted values: day, week, month. Case, spaces, hyphens and underscores are interchangeable.' - name: page_type in: query required: false schema: type: string enum: - all - news - forum - social - discussion example: all description: 'all, news, forum, social or discussion Accepted values: all, news, forum, social, discussion. Case, spaces, hyphens and underscores are interchangeable.' - name: internal_list_limit in: query required: false schema: type: string example: '10' description: Length of the embedded top-terms list (max 50) - name: depth in: query required: false schema: type: string example: '100' description: Items fetched PER SOURCE before bucketing (max 100) - name: filters in: query required: false schema: type: string example: source:eq:hackernews description: field:op:value segments joined by ; — see /v1/content_analysis/filters - 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/content_analysis/phrase-trends.json title: content_analysis/phrase-trends data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' bucket_count: description: Optional bucket count supplied by this operation. Null means unknown. type: - number - 'null' buckets: description: Optional buckets supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: bucket_end: description: Optional bucket end supplied by this operation. Null means unknown. type: - string - 'null' bucket_start: description: Optional bucket start supplied by this operation. Null means unknown. type: - string - 'null' by_source: description: Optional by source supplied by this operation. Null means unknown. type: - object - 'null' properties: google_news: description: Optional google news supplied by this operation. Null means unknown. type: - number - 'null' hackernews: description: Optional hackernews supplied by this operation. Null means unknown. type: - number - 'null' reddit: description: Optional reddit supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true date_from: description: Optional date from supplied by this operation. Null means unknown. type: - string - 'null' date_group: description: Optional date group supplied by this operation. Null means unknown. type: - string - 'null' date_to: description: Optional date to supplied by this operation. Null means unknown. type: - string - 'null' excluded: description: Optional excluded supplied by this operation. Null means unknown. type: - object - 'null' properties: out_of_window_mentions: description: Optional out of window mentions supplied by this operation. Null means unknown. type: - number - 'null' undated_mentions: description: Optional undated mentions supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true filters_applied: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} keyword: description: Optional keyword supplied by this operation. Null means unknown. type: - string - 'null' sentiment_method: description: Optional sentiment method supplied by this operation. Null means unknown. type: - object - 'null' properties: ai_used: description: Optional ai used supplied by this operation. Null means unknown. type: - boolean - 'null' kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' known_limits: description: Optional known limits supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' lexicon: description: Optional lexicon supplied by this operation. Null means unknown. type: - object - 'null' properties: diminishers: description: Optional diminishers supplied by this operation. Null means unknown. type: - number - 'null' intensifiers: description: Optional intensifiers supplied by this operation. Null means unknown. type: - number - 'null' negative_terms: description: Optional negative terms supplied by this operation. Null means unknown. type: - number - 'null' negators: description: Optional negators supplied by this operation. Null means unknown. type: - number - 'null' positive_terms: description: Optional positive terms supplied by this operation. Null means unknown. type: - number - 'null' total_terms: description: Optional total terms supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true modifiers: description: Optional modifiers supplied by this operation. Null means unknown. type: - object - 'null' properties: diminisher: description: Optional diminisher supplied by this operation. Null means unknown. type: - string - 'null' intensifier: description: Optional intensifier supplied by this operation. Null means unknown. type: - string - 'null' matching: description: Optional matching supplied by this operation. Null means unknown. type: - string - 'null' negation: description: Optional negation supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true scoring: description: Optional scoring supplied by this operation. Null means unknown. type: - string - 'null' thresholds: description: Optional thresholds supplied by this operation. Null means unknown. type: - object - 'null' properties: negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true sources: description: Optional sources supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: endpoint: description: Optional endpoint supplied by this operation. Null means unknown. type: - string - 'null' error: description: Optional error supplied by this operation. Null means unknown. type: - string - 'null' kept: description: Optional kept supplied by this operation. Null means unknown. type: - number - 'null' ok: description: Optional ok supplied by this operation. Null means unknown. type: - boolean - 'null' returned: description: Optional returned supplied by this operation. Null means unknown. type: - number - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true sources_unavailable: description: Optional sources unavailable supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true top_terms: description: Optional top terms supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' occurrences: description: Optional occurrences supplied by this operation. Null means unknown. type: - number - 'null' term: description: Optional term supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true totals: description: Optional totals supplied by this operation. Null means unknown. type: - object - 'null' properties: buckets_with_mentions: description: Optional buckets with mentions supplied by this operation. Null means unknown. type: - number - 'null' duplicates_removed: description: Optional duplicates removed supplied by this operation. Null means unknown. type: - number - 'null' gathered_before_filters: description: Optional gathered before filters supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' peak_bucket: description: Optional peak bucket supplied by this operation. Null means unknown. type: - object - 'null' properties: bucket_start: description: Optional bucket start supplied by this operation. Null means unknown. type: - string - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: max_score: description: Optional max score supplied by this operation. Null means unknown. type: - number - 'null' mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' median_score: description: Optional median score supplied by this operation. Null means unknown. type: - number - 'null' min_score: description: Optional min score supplied by this operation. Null means unknown. type: - number - 'null' negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - bucket_count properties: bucket_count: description: Optional bucket count supplied by this operation. Null means unknown. type: - number - required: - buckets properties: buckets: description: Optional buckets supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: bucket_end: description: Optional bucket end supplied by this operation. Null means unknown. type: - string - 'null' bucket_start: description: Optional bucket start supplied by this operation. Null means unknown. type: - string - 'null' by_source: description: Optional by source supplied by this operation. Null means unknown. type: - object - 'null' properties: google_news: description: Optional google news supplied by this operation. Null means unknown. type: - number - 'null' hackernews: description: Optional hackernews supplied by this operation. Null means unknown. type: - number - 'null' reddit: description: Optional reddit supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true - required: - date_from properties: date_from: description: Optional date from supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - date_group properties: date_group: description: Optional date group supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - date_to properties: date_to: description: Optional date to supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - excluded properties: excluded: description: Optional excluded supplied by this operation. Null means unknown. type: - object properties: out_of_window_mentions: description: Optional out of window mentions supplied by this operation. Null means unknown. type: - number - 'null' undated_mentions: description: Optional undated mentions supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - filters_applied properties: filters_applied: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - sentiment_method properties: sentiment_method: description: Optional sentiment method supplied by this operation. Null means unknown. type: - object properties: ai_used: description: Optional ai used supplied by this operation. Null means unknown. type: - boolean - 'null' kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' known_limits: description: Optional known limits supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' lexicon: description: Optional lexicon supplied by this operation. Null means unknown. type: - object - 'null' properties: diminishers: description: Optional diminishers supplied by this operation. Null means unknown. type: - number - 'null' intensifiers: description: Optional intensifiers supplied by this operation. Null means unknown. type: - number - 'null' negative_terms: description: Optional negative terms supplied by this operation. Null means unknown. type: - number - 'null' negators: description: Optional negators supplied by this operation. Null means unknown. type: - number - 'null' positive_terms: description: Optional positive terms supplied by this operation. Null means unknown. type: - number - 'null' total_terms: description: Optional total terms supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true modifiers: description: Optional modifiers supplied by this operation. Null means unknown. type: - object - 'null' properties: diminisher: description: Optional diminisher supplied by this operation. Null means unknown. type: - string - 'null' intensifier: description: Optional intensifier supplied by this operation. Null means unknown. type: - string - 'null' matching: description: Optional matching supplied by this operation. Null means unknown. type: - string - 'null' negation: description: Optional negation supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true scoring: description: Optional scoring supplied by this operation. Null means unknown. type: - string - 'null' thresholds: description: Optional thresholds supplied by this operation. Null means unknown. type: - object - 'null' properties: negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true - required: - sources properties: sources: description: Optional sources supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: endpoint: description: Optional endpoint supplied by this operation. Null means unknown. type: - string - 'null' error: description: Optional error supplied by this operation. Null means unknown. type: - string - 'null' kept: description: Optional kept supplied by this operation. Null means unknown. type: - number - 'null' ok: description: Optional ok supplied by this operation. Null means unknown. type: - boolean - 'null' returned: description: Optional returned supplied by this operation. Null means unknown. type: - number - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - sources_unavailable properties: sources_unavailable: description: Optional sources unavailable supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - top_terms properties: top_terms: description: Optional top terms supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' occurrences: description: Optional occurrences supplied by this operation. Null means unknown. type: - number - 'null' term: description: Optional term supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - totals properties: totals: description: Optional totals supplied by this operation. Null means unknown. type: - object properties: buckets_with_mentions: description: Optional buckets with mentions supplied by this operation. Null means unknown. type: - number - 'null' duplicates_removed: description: Optional duplicates removed supplied by this operation. Null means unknown. type: - number - 'null' gathered_before_filters: description: Optional gathered before filters supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' peak_bucket: description: Optional peak bucket supplied by this operation. Null means unknown. type: - object - 'null' properties: bucket_start: description: Optional bucket start supplied by this operation. Null means unknown. type: - string - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: max_score: description: Optional max score supplied by this operation. Null means unknown. type: - number - 'null' mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' median_score: description: Optional median score supplied by this operation. Null means unknown. type: - number - 'null' min_score: description: Optional min score supplied by this operation. Null means unknown. type: - number - 'null' negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true additionalProperties: true x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: - example bucket_count: 0 buckets: - bucket_end: example bucket_start: example by_source: google_news: 0 hackernews: 0 reddit: 0 mentions: 0 sentiment: mean_score: 0 negative: 0 neutral: 0 positive: 0 date_from: '2026-09-01T12:00:00Z' date_group: '2026-09-01T12:00:00Z' date_to: '2026-09-01T12:00:00Z' excluded: out_of_window_mentions: 0 undated_mentions: 0 filters_applied: [] keyword: example sentiment_method: ai_used: false kind: example known_limits: - example lexicon: diminishers: 0 intensifiers: 0 negative_terms: 0 negators: 0 positive_terms: 0 total_terms: 0 modifiers: diminisher: example intensifier: example matching: example negation: example scoring: example thresholds: negative: 0 positive: 0 sources: - endpoint: example error: example kept: 0 ok: false returned: 0 source: example status: 0 sources_unavailable: - reason: example source: example top_terms: - mentions: 0 occurrences: 0 term: example totals: buckets_with_mentions: 0 duplicates_removed: 0 gathered_before_filters: 0 mentions: 0 peak_bucket: bucket_start: example mentions: 0 sentiment: max_score: 0 mean_score: 0 median_score: 0 min_score: 0 negative: 0 neutral: 0 positive: 0 total: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 5 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/content_analysis/rating-distribution: get: operationId: content_analysis_rating_distribution tags: - Content Analysis summary: Keyword rating distribution description: Real 1-5 star histogram for a keyword that resolves to an App Store app, built from actual published reviews plus Apple's own lifetime average. If the keyword resolves to nothing rateable it returns 404 — no histogram is ever synthesised. Costs 3 credits per successful live response. parameters: - name: keyword in: query required: true schema: type: string example: Spotify description: Name of a rateable entity — currently an App Store app - name: country in: query required: false schema: type: string example: us description: 2-letter App Store storefront (default us); filters=location_code:eq:gb works too - name: depth in: query required: false schema: type: string example: '3' description: Pages of up to 50 reviews to sample (max 5) - name: filters in: query required: false schema: type: string example: location_code:eq:gb description: Only location_code applies here — see /v1/content_analysis/filters - 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/content_analysis/rating-distribution.json title: content_analysis/rating-distribution data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' distribution: description: Optional distribution supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' rating: description: Source rating; read its accompanying scale and vote count. type: - number - 'null' share: description: Optional share supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true filters_applied: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} histogram: description: Optional histogram supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true keyword: description: Optional keyword supplied by this operation. Null means unknown. type: - string - 'null' mean_rating: description: Optional mean rating supplied by this operation. Null means unknown. type: - number - 'null' resolved_entity: description: Optional resolved entity supplied by this operation. Null means unknown. type: - object - 'null' properties: developer: description: Optional developer supplied by this operation. Null means unknown. type: - string - 'null' exact_name_match: description: Optional exact name match supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' search_rank: description: Optional search rank supplied by this operation. Null means unknown. type: - number - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true reviews_sampled: description: Optional reviews sampled supplied by this operation. Null means unknown. type: - number - 'null' sources: description: Optional sources supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: endpoint: description: Optional endpoint supplied by this operation. Null means unknown. type: - string - 'null' ok: description: Optional ok supplied by this operation. Null means unknown. type: - boolean - 'null' returned: description: Optional returned supplied by this operation. Null means unknown. type: - number - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true sources_unavailable: description: Optional sources unavailable supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true store_reported: description: Optional store reported supplied by this operation. Null means unknown. type: - object - 'null' properties: average_rating: description: Optional average rating supplied by this operation. Null means unknown. type: - number - 'null' note: description: Optional note supplied by this operation. Null means unknown. type: - string - 'null' rating_count: description: Optional rating count supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true storefront: description: Optional storefront supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - distribution properties: distribution: description: Optional distribution supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' rating: description: Source rating; read its accompanying scale and vote count. type: - number - 'null' share: description: Optional share supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - filters_applied properties: filters_applied: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - histogram properties: histogram: description: Optional histogram supplied by this operation. Null means unknown. type: - object properties: {} additionalProperties: true - required: - mean_rating properties: mean_rating: description: Optional mean rating supplied by this operation. Null means unknown. type: - number - required: - resolved_entity properties: resolved_entity: description: Optional resolved entity supplied by this operation. Null means unknown. type: - object properties: developer: description: Optional developer supplied by this operation. Null means unknown. type: - string - 'null' exact_name_match: description: Optional exact name match supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' search_rank: description: Optional search rank supplied by this operation. Null means unknown. type: - number - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - reviews_sampled properties: reviews_sampled: description: Optional reviews sampled supplied by this operation. Null means unknown. type: - number - required: - sources properties: sources: description: Optional sources supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: endpoint: description: Optional endpoint supplied by this operation. Null means unknown. type: - string - 'null' ok: description: Optional ok supplied by this operation. Null means unknown. type: - boolean - 'null' returned: description: Optional returned supplied by this operation. Null means unknown. type: - number - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - sources_unavailable properties: sources_unavailable: description: Optional sources unavailable supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - store_reported properties: store_reported: description: Optional store reported supplied by this operation. Null means unknown. type: - object properties: average_rating: description: Optional average rating supplied by this operation. Null means unknown. type: - number - 'null' note: description: Optional note supplied by this operation. Null means unknown. type: - string - 'null' rating_count: description: Optional rating count supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - storefront properties: storefront: description: Optional storefront supplied by this operation. Null means unknown. 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: - _warnings: - example distribution: - count: 0 rating: 0 share: 0 filters_applied: [] histogram: {} keyword: example mean_rating: 0 resolved_entity: developer: example exact_name_match: false id: example name: example search_rank: 0 type: example url: https://example.com/example reviews_sampled: 0 sources: - endpoint: example ok: false returned: 0 source: example sources_unavailable: - reason: example source: example store_reported: average_rating: 0 note: example rating_count: 0 storefront: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 3 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/content_analysis/search: get: operationId: content_analysis_search tags: - Content Analysis summary: Keyword mention search description: Web citations of a keyword from news, Hacker News and Reddit with deterministic per-mention sentiment (in-adapter lexicon, no AI), Monocrawl category labels and per-source provenance. Fans out to 3 upstreams; coverage is partial and every response names what it could not consult. Costs 3 credits per successful live response. parameters: - name: keyword in: query required: true schema: type: string example: kubernetes description: Phrase to find mentions of - name: page_type in: query required: false schema: type: string enum: - all - news - forum - social - discussion example: all description: 'all, news, forum, social or discussion — maps onto our source roster; review/blog/ecommerce classes are rejected with an explanation rather than silently served from the wrong sources Accepted values: all, news, forum, social, discussion. Case, spaces, hyphens and underscores are interchangeable.' - name: search_mode in: query required: false schema: type: string enum: - as_is - one_per_domain example: as_is description: 'as_is (default) or one_per_domain (keep the first mention per publisher) Accepted values: as_is, one_per_domain. Case, spaces, hyphens and underscores are interchangeable.' - name: limit in: query required: false schema: type: string example: '25' description: Mentions per page after merging (max 100) - name: cursor in: query required: false schema: type: string example: '25' description: Offset into the merged result set, from a previous response - name: order_by in: query required: false schema: type: string enum: - published_at:desc - published_at:asc - sentiment:desc - sentiment:asc - source - relevance example: published_at:desc description: 'published_at:desc|asc, sentiment:desc|asc, source or relevance Accepted values: published_at:desc, published_at:asc, sentiment:desc, sentiment:asc, source, relevance. Case, spaces, hyphens and underscores are interchangeable.' - name: depth in: query required: false schema: type: string example: '25' description: Items fetched PER SOURCE before merging (max 100) - name: positive_connotation_threshold in: query required: false schema: type: string example: '0.25' description: Score in (0,1] at or above which a mention is labelled positive - name: sentiments_connotation_threshold in: query required: false schema: type: string example: '0.25' description: Score magnitude at or below which a mention is labelled negative - name: filters in: query required: false schema: type: string example: source:in:hackernews,reddit;sentiment:eq:negative description: field:op:value segments joined by ; — see /v1/content_analysis/filters - 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/content_analysis/search.json title: content_analysis/search data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' dropped: description: Optional dropped supplied by this operation. Null means unknown. type: - number - 'null' duplicates_removed: description: Optional duplicates removed supplied by this operation. Null means unknown. type: - number - 'null' filters_applied: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} gathered: description: Optional gathered supplied by this operation. Null means unknown. type: - number - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: author: description: Public author information supplied with this record. type: - string - 'null' categories: description: Optional categories supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' engagement: description: Optional engagement supplied by this operation. Null means unknown. type: - object - 'null' properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' score: description: Optional score supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true matched_terms: description: Optional matched terms supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true primary_category: description: Optional primary category supplied by this operation. Null means unknown. type: - string - 'null' published_at: description: Source publication time when available. type: - string - 'null' publisher: description: Optional publisher supplied by this operation. Null means unknown. type: - string - 'null' raw_sentiment_score: description: Optional raw sentiment score supplied by this operation. Null means unknown. type: - number - 'null' sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: label: description: Optional label supplied by this operation. Null means unknown. type: - string - 'null' score: description: Optional score supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' text_source: description: Optional text source supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - author properties: author: description: Public author information supplied with this record. type: - string minLength: 1 - required: - categories properties: categories: description: Optional categories supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - engagement properties: engagement: description: Optional engagement supplied by this operation. Null means unknown. type: - object properties: comments: description: Optional comments supplied by this operation. Null means unknown. type: - number - 'null' score: description: Optional score supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - matched_terms properties: matched_terms: description: Optional matched terms supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true - required: - primary_category properties: primary_category: description: Optional primary category supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - published_at properties: published_at: description: Source publication time when available. type: - string minLength: 1 - required: - publisher properties: publisher: description: Optional publisher supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - raw_sentiment_score properties: raw_sentiment_score: description: Optional raw sentiment score supplied by this operation. Null means unknown. type: - number - required: - sentiment properties: sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object properties: label: description: Optional label supplied by this operation. Null means unknown. type: - string - 'null' score: description: Optional score supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - source properties: source: description: Optional source supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - text_source properties: text_source: description: Optional text source supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 keyword: description: Optional keyword supplied by this operation. Null means unknown. type: - string - 'null' order_by: description: Optional order by supplied by this operation. Null means unknown. type: - string - 'null' search_mode: description: Optional search mode supplied by this operation. Null means unknown. type: - string - 'null' sentiment_method: description: Optional sentiment method supplied by this operation. Null means unknown. type: - object - 'null' properties: ai_used: description: Optional ai used supplied by this operation. Null means unknown. type: - boolean - 'null' kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' known_limits: description: Optional known limits supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' lexicon: description: Optional lexicon supplied by this operation. Null means unknown. type: - object - 'null' properties: diminishers: description: Optional diminishers supplied by this operation. Null means unknown. type: - number - 'null' intensifiers: description: Optional intensifiers supplied by this operation. Null means unknown. type: - number - 'null' negative_terms: description: Optional negative terms supplied by this operation. Null means unknown. type: - number - 'null' negators: description: Optional negators supplied by this operation. Null means unknown. type: - number - 'null' positive_terms: description: Optional positive terms supplied by this operation. Null means unknown. type: - number - 'null' total_terms: description: Optional total terms supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true modifiers: description: Optional modifiers supplied by this operation. Null means unknown. type: - object - 'null' properties: diminisher: description: Optional diminisher supplied by this operation. Null means unknown. type: - string - 'null' intensifier: description: Optional intensifier supplied by this operation. Null means unknown. type: - string - 'null' matching: description: Optional matching supplied by this operation. Null means unknown. type: - string - 'null' negation: description: Optional negation supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true scoring: description: Optional scoring supplied by this operation. Null means unknown. type: - string - 'null' thresholds: description: Optional thresholds supplied by this operation. Null means unknown. type: - object - 'null' properties: negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true sources: description: Optional sources supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: endpoint: description: Optional endpoint supplied by this operation. Null means unknown. type: - string - 'null' error: description: Optional error supplied by this operation. Null means unknown. type: - string - 'null' kept: description: Optional kept supplied by this operation. Null means unknown. type: - number - 'null' ok: description: Optional ok supplied by this operation. Null means unknown. type: - boolean - 'null' returned: description: Optional returned supplied by this operation. Null means unknown. type: - number - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true sources_unavailable: description: Optional sources unavailable supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true total_matched: description: Optional total matched supplied by this operation. Null means unknown. 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: - _warnings: - example count: 0 cursor: null dropped: 0 duplicates_removed: 0 filters_applied: [] gathered: 0 items: - author: example categories: - example engagement: comments: 0 score: 0 matched_terms: - {} primary_category: example published_at: '2026-09-01T12:00:00Z' publisher: example raw_sentiment_score: 0 sentiment: label: example score: 0 source: example text_source: example title: example url: https://example.com/example keyword: example order_by: example search_mode: example sentiment_method: ai_used: false kind: example known_limits: - example lexicon: diminishers: 0 intensifiers: 0 negative_terms: 0 negators: 0 positive_terms: 0 total_terms: 0 modifiers: diminisher: example intensifier: example matching: example negation: example scoring: example thresholds: negative: 0 positive: 0 sources: - endpoint: example error: example kept: 0 ok: false returned: 0 source: example status: 0 sources_unavailable: - reason: example source: example total_matched: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 3 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/content_analysis/sentiment: get: operationId: content_analysis_sentiment tags: - Content Analysis summary: Keyword sentiment breakdown description: Positive / neutral / negative split for a keyword with mean, median and a score histogram, plus the most positive and most negative mentions. Lexicon-based and fully deterministic — the method, its thresholds and its limits are returned with every response. Costs 3 credits per successful live response. parameters: - name: keyword in: query required: true schema: type: string example: kubernetes description: Phrase to score - name: page_type in: query required: false schema: type: string enum: - all - news - forum - social - discussion example: all description: 'all, news, forum, social or discussion Accepted values: all, news, forum, social, discussion. Case, spaces, hyphens and underscores are interchangeable.' - name: positive_connotation_threshold in: query required: false schema: type: string example: '0.25' description: Score in (0,1] at or above which a mention is positive - name: sentiments_connotation_threshold in: query required: false schema: type: string example: '0.25' description: Score magnitude at or below which a mention is negative - name: depth in: query required: false schema: type: string example: '50' description: Items fetched PER SOURCE before aggregating (max 100) - name: filters in: query required: false schema: type: string example: source:eq:hackernews description: field:op:value segments joined by ; — see /v1/content_analysis/filters - 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/content_analysis/sentiment.json title: content_analysis/sentiment data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' by_source: description: Optional by source supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: max_score: description: Optional max score supplied by this operation. Null means unknown. type: - number - 'null' mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' median_score: description: Optional median score supplied by this operation. Null means unknown. type: - number - 'null' min_score: description: Optional min score supplied by this operation. Null means unknown. type: - number - 'null' negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true counts: description: Optional counts supplied by this operation. Null means unknown. type: - object - 'null' properties: negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true filters_applied: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} keyword: description: Optional keyword supplied by this operation. Null means unknown. type: - string - 'null' max_score: description: Optional max score supplied by this operation. Null means unknown. type: - number - 'null' mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' median_score: description: Optional median score supplied by this operation. Null means unknown. type: - number - 'null' min_score: description: Optional min score supplied by this operation. Null means unknown. type: - number - 'null' most_negative: description: Optional most negative supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: matched_terms: description: Optional matched terms supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true published_at: description: Source publication time when available. type: - string - 'null' sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: label: description: Optional label supplied by this operation. Null means unknown. type: - string - 'null' score: description: Optional score supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true most_positive: description: Optional most positive supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: matched_terms: description: Optional matched terms supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true published_at: description: Source publication time when available. type: - string - 'null' sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: label: description: Optional label supplied by this operation. Null means unknown. type: - string - 'null' score: description: Optional score supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true score_histogram: description: Optional score histogram supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: from: description: Optional from supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' to: description: Optional to supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true sentiment_method: description: Optional sentiment method supplied by this operation. Null means unknown. type: - object - 'null' properties: ai_used: description: Optional ai used supplied by this operation. Null means unknown. type: - boolean - 'null' kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' known_limits: description: Optional known limits supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' lexicon: description: Optional lexicon supplied by this operation. Null means unknown. type: - object - 'null' properties: diminishers: description: Optional diminishers supplied by this operation. Null means unknown. type: - number - 'null' intensifiers: description: Optional intensifiers supplied by this operation. Null means unknown. type: - number - 'null' negative_terms: description: Optional negative terms supplied by this operation. Null means unknown. type: - number - 'null' negators: description: Optional negators supplied by this operation. Null means unknown. type: - number - 'null' positive_terms: description: Optional positive terms supplied by this operation. Null means unknown. type: - number - 'null' total_terms: description: Optional total terms supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true modifiers: description: Optional modifiers supplied by this operation. Null means unknown. type: - object - 'null' properties: diminisher: description: Optional diminisher supplied by this operation. Null means unknown. type: - string - 'null' intensifier: description: Optional intensifier supplied by this operation. Null means unknown. type: - string - 'null' matching: description: Optional matching supplied by this operation. Null means unknown. type: - string - 'null' negation: description: Optional negation supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true scoring: description: Optional scoring supplied by this operation. Null means unknown. type: - string - 'null' thresholds: description: Optional thresholds supplied by this operation. Null means unknown. type: - object - 'null' properties: negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true share: description: Optional share supplied by this operation. Null means unknown. type: - object - 'null' properties: negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true sources: description: Optional sources supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: endpoint: description: Optional endpoint supplied by this operation. Null means unknown. type: - string - 'null' error: description: Optional error supplied by this operation. Null means unknown. type: - string - 'null' kept: description: Optional kept supplied by this operation. Null means unknown. type: - number - 'null' ok: description: Optional ok supplied by this operation. Null means unknown. type: - boolean - 'null' returned: description: Optional returned supplied by this operation. Null means unknown. type: - number - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true sources_unavailable: description: Optional sources unavailable supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true unscored_mentions: description: Optional unscored mentions supplied by this operation. Null means unknown. type: - number - 'null' volume: description: Optional volume supplied by this operation. Null means unknown. type: - object - 'null' properties: duplicates_removed: description: Optional duplicates removed supplied by this operation. Null means unknown. type: - number - 'null' gathered_before_filters: description: Optional gathered before filters supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - by_source properties: by_source: description: Optional by source supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: max_score: description: Optional max score supplied by this operation. Null means unknown. type: - number - 'null' mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' median_score: description: Optional median score supplied by this operation. Null means unknown. type: - number - 'null' min_score: description: Optional min score supplied by this operation. Null means unknown. type: - number - 'null' negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true - required: - counts properties: counts: description: Optional counts supplied by this operation. Null means unknown. type: - object properties: negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true - required: - filters_applied properties: filters_applied: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - max_score properties: max_score: description: Optional max score supplied by this operation. Null means unknown. type: - number - required: - mean_score properties: mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - required: - median_score properties: median_score: description: Optional median score supplied by this operation. Null means unknown. type: - number - required: - min_score properties: min_score: description: Optional min score supplied by this operation. Null means unknown. type: - number - required: - most_negative properties: most_negative: description: Optional most negative supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: matched_terms: description: Optional matched terms supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true published_at: description: Source publication time when available. type: - string - 'null' sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: label: description: Optional label supplied by this operation. Null means unknown. type: - string - 'null' score: description: Optional score supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - most_positive properties: most_positive: description: Optional most positive supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: matched_terms: description: Optional matched terms supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true published_at: description: Source publication time when available. type: - string - 'null' sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: label: description: Optional label supplied by this operation. Null means unknown. type: - string - 'null' score: description: Optional score supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - score_histogram properties: score_histogram: description: Optional score histogram supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: from: description: Optional from supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' to: description: Optional to supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - sentiment_method properties: sentiment_method: description: Optional sentiment method supplied by this operation. Null means unknown. type: - object properties: ai_used: description: Optional ai used supplied by this operation. Null means unknown. type: - boolean - 'null' kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' known_limits: description: Optional known limits supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' lexicon: description: Optional lexicon supplied by this operation. Null means unknown. type: - object - 'null' properties: diminishers: description: Optional diminishers supplied by this operation. Null means unknown. type: - number - 'null' intensifiers: description: Optional intensifiers supplied by this operation. Null means unknown. type: - number - 'null' negative_terms: description: Optional negative terms supplied by this operation. Null means unknown. type: - number - 'null' negators: description: Optional negators supplied by this operation. Null means unknown. type: - number - 'null' positive_terms: description: Optional positive terms supplied by this operation. Null means unknown. type: - number - 'null' total_terms: description: Optional total terms supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true modifiers: description: Optional modifiers supplied by this operation. Null means unknown. type: - object - 'null' properties: diminisher: description: Optional diminisher supplied by this operation. Null means unknown. type: - string - 'null' intensifier: description: Optional intensifier supplied by this operation. Null means unknown. type: - string - 'null' matching: description: Optional matching supplied by this operation. Null means unknown. type: - string - 'null' negation: description: Optional negation supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true scoring: description: Optional scoring supplied by this operation. Null means unknown. type: - string - 'null' thresholds: description: Optional thresholds supplied by this operation. Null means unknown. type: - object - 'null' properties: negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true - required: - share properties: share: description: Optional share supplied by this operation. Null means unknown. type: - object properties: negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - sources properties: sources: description: Optional sources supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: endpoint: description: Optional endpoint supplied by this operation. Null means unknown. type: - string - 'null' error: description: Optional error supplied by this operation. Null means unknown. type: - string - 'null' kept: description: Optional kept supplied by this operation. Null means unknown. type: - number - 'null' ok: description: Optional ok supplied by this operation. Null means unknown. type: - boolean - 'null' returned: description: Optional returned supplied by this operation. Null means unknown. type: - number - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - sources_unavailable properties: sources_unavailable: description: Optional sources unavailable supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - unscored_mentions properties: unscored_mentions: description: Optional unscored mentions supplied by this operation. Null means unknown. type: - number - required: - volume properties: volume: description: Optional volume supplied by this operation. Null means unknown. type: - object properties: duplicates_removed: description: Optional duplicates removed supplied by this operation. Null means unknown. type: - number - 'null' gathered_before_filters: description: Optional gathered before filters supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. 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: - _warnings: - example by_source: - max_score: 0 mean_score: 0 median_score: 0 min_score: 0 negative: 0 neutral: 0 positive: 0 source: example total: 0 counts: negative: 0 neutral: 0 positive: 0 total: 0 filters_applied: [] keyword: example max_score: 0 mean_score: 0 median_score: 0 min_score: 0 most_negative: - matched_terms: - {} published_at: '2026-09-01T12:00:00Z' sentiment: label: example score: 0 source: example title: example url: https://example.com/example most_positive: - matched_terms: - {} published_at: '2026-09-01T12:00:00Z' sentiment: label: example score: 0 source: example title: example url: https://example.com/example score_histogram: - from: 0 mentions: 0 to: 0 sentiment_method: ai_used: false kind: example known_limits: - example lexicon: diminishers: 0 intensifiers: 0 negative_terms: 0 negators: 0 positive_terms: 0 total_terms: 0 modifiers: diminisher: example intensifier: example matching: example negation: example scoring: example thresholds: negative: 0 positive: 0 share: negative: 0 neutral: 0 positive: 0 sources: - endpoint: example error: example kept: 0 ok: false returned: 0 source: example status: 0 sources_unavailable: - reason: example source: example unscored_mentions: 0 volume: duplicates_removed: 0 gathered_before_filters: 0 mentions: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 3 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/content_analysis/summary: get: operationId: content_analysis_summary tags: - Content Analysis summary: Keyword mention summary description: 'Aggregate view of a keyword''s mentions: volume, per-source breakdown, sentiment split, category mix, top publishers and top terms — all computed deterministically from the mentions we could reach. Costs 3 credits per successful live response.' parameters: - name: keyword in: query required: true schema: type: string example: kubernetes description: Phrase to summarise mentions of - name: page_type in: query required: false schema: type: string enum: - all - news - forum - social - discussion example: all description: 'all, news, forum, social or discussion Accepted values: all, news, forum, social, discussion. Case, spaces, hyphens and underscores are interchangeable.' - name: positive_connotation_threshold in: query required: false schema: type: string example: '0.25' description: Score in (0,1] at or above which a mention is positive - name: sentiments_connotation_threshold in: query required: false schema: type: string example: '0.25' description: Score magnitude at or below which a mention is negative - name: internal_list_limit in: query required: false schema: type: string example: '10' description: Length of the embedded top-terms / category / publisher lists (max 50) - name: depth in: query required: false schema: type: string example: '50' description: Items fetched PER SOURCE before aggregating (max 100) - name: filters in: query required: false schema: type: string example: category:eq:reliability_outage description: field:op:value segments joined by ; — see /v1/content_analysis/filters - 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/content_analysis/summary.json title: content_analysis/summary data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' by_category: description: Optional by category supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: code: description: Optional code supplied by this operation. Null means unknown. type: - string - 'null' mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true by_source: description: Optional by source supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: max_score: description: Optional max score supplied by this operation. Null means unknown. type: - number - 'null' mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' median_score: description: Optional median score supplied by this operation. Null means unknown. type: - number - 'null' min_score: description: Optional min score supplied by this operation. Null means unknown. type: - number - 'null' negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true filters_applied: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} first_mention_at: description: Optional first mention at supplied by this operation. Null means unknown. type: - string - 'null' keyword: description: Optional keyword supplied by this operation. Null means unknown. type: - string - 'null' last_mention_at: description: Optional last mention at supplied by this operation. Null means unknown. type: - string - 'null' sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: max_score: description: Optional max score supplied by this operation. Null means unknown. type: - number - 'null' mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' median_score: description: Optional median score supplied by this operation. Null means unknown. type: - number - 'null' min_score: description: Optional min score supplied by this operation. Null means unknown. type: - number - 'null' negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true sentiment_method: description: Optional sentiment method supplied by this operation. Null means unknown. type: - object - 'null' properties: ai_used: description: Optional ai used supplied by this operation. Null means unknown. type: - boolean - 'null' kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' known_limits: description: Optional known limits supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' lexicon: description: Optional lexicon supplied by this operation. Null means unknown. type: - object - 'null' properties: diminishers: description: Optional diminishers supplied by this operation. Null means unknown. type: - number - 'null' intensifiers: description: Optional intensifiers supplied by this operation. Null means unknown. type: - number - 'null' negative_terms: description: Optional negative terms supplied by this operation. Null means unknown. type: - number - 'null' negators: description: Optional negators supplied by this operation. Null means unknown. type: - number - 'null' positive_terms: description: Optional positive terms supplied by this operation. Null means unknown. type: - number - 'null' total_terms: description: Optional total terms supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true modifiers: description: Optional modifiers supplied by this operation. Null means unknown. type: - object - 'null' properties: diminisher: description: Optional diminisher supplied by this operation. Null means unknown. type: - string - 'null' intensifier: description: Optional intensifier supplied by this operation. Null means unknown. type: - string - 'null' matching: description: Optional matching supplied by this operation. Null means unknown. type: - string - 'null' negation: description: Optional negation supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true scoring: description: Optional scoring supplied by this operation. Null means unknown. type: - string - 'null' thresholds: description: Optional thresholds supplied by this operation. Null means unknown. type: - object - 'null' properties: negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true sources: description: Optional sources supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: endpoint: description: Optional endpoint supplied by this operation. Null means unknown. type: - string - 'null' error: description: Optional error supplied by this operation. Null means unknown. type: - string - 'null' kept: description: Optional kept supplied by this operation. Null means unknown. type: - number - 'null' ok: description: Optional ok supplied by this operation. Null means unknown. type: - boolean - 'null' returned: description: Optional returned supplied by this operation. Null means unknown. type: - number - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true sources_unavailable: description: Optional sources unavailable supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true top_publishers: description: Optional top publishers supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' publisher: description: Optional publisher supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true top_terms: description: Optional top terms supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' occurrences: description: Optional occurrences supplied by this operation. Null means unknown. type: - number - 'null' term: description: Optional term supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true uncategorised_mentions: description: Optional uncategorised mentions supplied by this operation. Null means unknown. type: - number - 'null' volume: description: Optional volume supplied by this operation. Null means unknown. type: - object - 'null' properties: duplicates_removed: description: Optional duplicates removed supplied by this operation. Null means unknown. type: - number - 'null' gathered_before_filters: description: Optional gathered before filters supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' sources_attempted: description: Optional sources attempted supplied by this operation. Null means unknown. type: - number - 'null' sources_succeeded: description: Optional sources succeeded supplied by this operation. Null means unknown. type: - number - 'null' undated: description: Optional undated supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true allOf: - anyOf: - required: - by_category properties: by_category: description: Optional by category supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: code: description: Optional code supplied by this operation. Null means unknown. type: - string - 'null' mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - by_source properties: by_source: description: Optional by source supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object - 'null' properties: max_score: description: Optional max score supplied by this operation. Null means unknown. type: - number - 'null' mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' median_score: description: Optional median score supplied by this operation. Null means unknown. type: - number - 'null' min_score: description: Optional min score supplied by this operation. Null means unknown. type: - number - 'null' negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - filters_applied properties: filters_applied: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - first_mention_at properties: first_mention_at: description: Optional first mention at supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - last_mention_at properties: last_mention_at: description: Optional last mention at supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - sentiment properties: sentiment: description: Optional sentiment supplied by this operation. Null means unknown. type: - object properties: max_score: description: Optional max score supplied by this operation. Null means unknown. type: - number - 'null' mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' median_score: description: Optional median score supplied by this operation. Null means unknown. type: - number - 'null' min_score: description: Optional min score supplied by this operation. Null means unknown. type: - number - 'null' negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' neutral: description: Optional neutral supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true - required: - sentiment_method properties: sentiment_method: description: Optional sentiment method supplied by this operation. Null means unknown. type: - object properties: ai_used: description: Optional ai used supplied by this operation. Null means unknown. type: - boolean - 'null' kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' known_limits: description: Optional known limits supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' lexicon: description: Optional lexicon supplied by this operation. Null means unknown. type: - object - 'null' properties: diminishers: description: Optional diminishers supplied by this operation. Null means unknown. type: - number - 'null' intensifiers: description: Optional intensifiers supplied by this operation. Null means unknown. type: - number - 'null' negative_terms: description: Optional negative terms supplied by this operation. Null means unknown. type: - number - 'null' negators: description: Optional negators supplied by this operation. Null means unknown. type: - number - 'null' positive_terms: description: Optional positive terms supplied by this operation. Null means unknown. type: - number - 'null' total_terms: description: Optional total terms supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true modifiers: description: Optional modifiers supplied by this operation. Null means unknown. type: - object - 'null' properties: diminisher: description: Optional diminisher supplied by this operation. Null means unknown. type: - string - 'null' intensifier: description: Optional intensifier supplied by this operation. Null means unknown. type: - string - 'null' matching: description: Optional matching supplied by this operation. Null means unknown. type: - string - 'null' negation: description: Optional negation supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true scoring: description: Optional scoring supplied by this operation. Null means unknown. type: - string - 'null' thresholds: description: Optional thresholds supplied by this operation. Null means unknown. type: - object - 'null' properties: negative: description: Optional negative supplied by this operation. Null means unknown. type: - number - 'null' positive: description: Optional positive supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true additionalProperties: true - required: - sources properties: sources: description: Optional sources supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: endpoint: description: Optional endpoint supplied by this operation. Null means unknown. type: - string - 'null' error: description: Optional error supplied by this operation. Null means unknown. type: - string - 'null' kept: description: Optional kept supplied by this operation. Null means unknown. type: - number - 'null' ok: description: Optional ok supplied by this operation. Null means unknown. type: - boolean - 'null' returned: description: Optional returned supplied by this operation. Null means unknown. type: - number - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - sources_unavailable properties: sources_unavailable: description: Optional sources unavailable supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: reason: description: Optional reason supplied by this operation. Null means unknown. type: - string - 'null' source: description: Optional source supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - top_publishers properties: top_publishers: description: Optional top publishers supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: mean_score: description: Optional mean score supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' publisher: description: Optional publisher supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - top_terms properties: top_terms: description: Optional top terms supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' occurrences: description: Optional occurrences supplied by this operation. Null means unknown. type: - number - 'null' term: description: Optional term supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - uncategorised_mentions properties: uncategorised_mentions: description: Optional uncategorised mentions supplied by this operation. Null means unknown. type: - number - required: - volume properties: volume: description: Optional volume supplied by this operation. Null means unknown. type: - object properties: duplicates_removed: description: Optional duplicates removed supplied by this operation. Null means unknown. type: - number - 'null' gathered_before_filters: description: Optional gathered before filters supplied by this operation. Null means unknown. type: - number - 'null' mentions: description: Optional mentions supplied by this operation. Null means unknown. type: - number - 'null' sources_attempted: description: Optional sources attempted supplied by this operation. Null means unknown. type: - number - 'null' sources_succeeded: description: Optional sources succeeded supplied by this operation. Null means unknown. type: - number - 'null' undated: description: Optional undated supplied by this operation. Null means unknown. 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: - _warnings: - example by_category: - code: example mean_score: 0 mentions: 0 name: example by_source: - mentions: 0 sentiment: max_score: 0 mean_score: 0 median_score: 0 min_score: 0 negative: 0 neutral: 0 positive: 0 total: 0 source: example filters_applied: [] first_mention_at: '2026-09-01T12:00:00Z' keyword: example last_mention_at: '2026-09-01T12:00:00Z' sentiment: max_score: 0 mean_score: 0 median_score: 0 min_score: 0 negative: 0 neutral: 0 positive: 0 total: 0 sentiment_method: ai_used: false kind: example known_limits: - example lexicon: diminishers: 0 intensifiers: 0 negative_terms: 0 negators: 0 positive_terms: 0 total_terms: 0 modifiers: diminisher: example intensifier: example matching: example negation: example scoring: example thresholds: negative: 0 positive: 0 sources: - endpoint: example error: example kept: 0 ok: false returned: 0 source: example status: 0 sources_unavailable: - reason: example source: example top_publishers: - mean_score: 0 mentions: 0 publisher: example top_terms: - mentions: 0 occurrences: 0 term: example uncategorised_mentions: 0 volume: duplicates_removed: 0 gathered_before_filters: 0 mentions: 0 sources_attempted: 0 sources_succeeded: 0 undated: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 3 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)