> ## Documentation Index > Fetch the complete documentation index at: https://clair.im/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search news > Keyword-first search and newest-first corpus traversal with source, time, revision, sort, and cursor controls. ## OpenAPI ````yaml news-api/openapi.json GET /v1/news openapi: 3.0.3 info: title: Clair News API version: 1.0.0 description: >- Keyword-first search over a continuously maintained English-language news index. Search titles and cleaned content with familiar web syntax, or omit the query to walk canonical articles newest first. Public requests read Clair's prebuilt index only; they never crawl a caller-supplied URL or invoke an embedding model. servers: - url: https://clair-news-api.p.rapidapi.com description: RapidAPI gateway. Use the exact host shown on the Clair News API listing. security: - rapidApiKey: [] paths: /v1/news: get: summary: Search news or walk the corpus description: >- Send `q` to search article titles and cleaned content with English full-text search. Omit `q` to return canonical articles newest first. Quoted phrases, uppercase `OR`, and minus-prefixed exclusions are supported. Source, category, and publication-time filters work in both modes. `sort_by=published_at` is the default and is suitable for monitoring. `sort_by=relevance` requires `q`. Pages use an opaque cursor bound to the query, filters, sort, and revision mode. Repeat the same inputs with `next_cursor` until it is null. By default, only the canonical record for each publisher URL is returned. Set `include_edits=true` to include later in-place revisions. Returned snippets are capped at 2,000 characters and their state is explicit through `content_available` and `content_truncated`. operationId: searchNews parameters: - name: q in: query description: >- English full-text query. Supports quoted phrases, uppercase `OR`, and minus-prefixed exclusions. A stopword-only query returns `empty_query`. schema: type: string minLength: 1 maxLength: 300 example: '"central bank" OR inflation -sports' - name: sources in: query description: >- Comma-separated exact names from `GET /v1/sources`, at most 50. Mutually exclusive with `exclude_sources`. schema: type: string minLength: 1 maxLength: 5000 example: Al Jazeera English,Deutsche Welle (English) - name: exclude_sources in: query description: >- Comma-separated exact names from `GET /v1/sources`, at most 50. Mutually exclusive with `sources`. schema: type: string minLength: 1 maxLength: 5000 - name: from in: query description: Inclusive RFC 3339 lower bound on publisher time. schema: type: string format: date-time example: '2026-07-01T00:00:00Z' - name: to in: query description: >- Inclusive RFC 3339 upper bound on publisher time. Must be later than or equal to `from`. schema: type: string format: date-time example: '2026-07-31T23:59:59Z' - name: sort_by in: query description: Result ordering. Relevance sorting requires `q`. schema: type: string enum: - published_at - relevance default: published_at - name: category in: query description: >- Deterministic publisher-section category. Event facets such as elections, crime, conflict, and disasters are queried through `q`, not represented as mutually exclusive categories. schema: type: string enum: - general - world - politics - business - technology - science - health - sports - entertainment - environment - name: include_edits in: query description: >- Include later revisions that share a publisher URL. The default returns only canonical records. schema: $ref: '#/components/schemas/BooleanQuery' example: 'false' - name: limit in: query description: Maximum items in this page. schema: type: integer minimum: 1 maximum: 100 default: 25 - name: cursor in: query description: >- Opaque `next_cursor` from the preceding page. Reuse it only with the exact query, filters, sort, and revision mode that created it. schema: type: string minLength: 1 maxLength: 1024 responses: '200': description: A page of news items. content: application/json: schema: $ref: '#/components/schemas/NewsSearchResponse' '400': description: '`bad_request`, `bad_cursor`, `empty_query`, or `unknown_source`.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing or invalid RapidAPI authorization. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: RapidAPI plan rate limit exceeded. '500': description: Unexpected internal error. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: >- The platform or News product is unavailable, or the endpoint is at capacity. Honor `Retry-After`. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '504': description: The request exceeded its processing deadline. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: BooleanQuery: type: string enum: - 'true' - '1' - 'yes' - 'false' - '0' - 'no' default: 'false' NewsSearchResponse: type: object additionalProperties: false required: - query - language - sort_by - count - items - next_cursor properties: query: type: string nullable: true description: The supplied query, or null for a chronological corpus walk. example: '"central bank" OR inflation -sports' language: type: string enum: - en sort_by: type: string enum: - published_at - relevance count: type: integer minimum: 0 maximum: 100 description: Number of items in this page. items: type: array items: $ref: '#/components/schemas/NewsItem' next_cursor: type: string nullable: true description: Opaque continuation token, or null when this traversal is complete. ErrorEnvelope: type: object required: - error properties: error: type: string description: Stable machine-readable code. detail: description: >- Human-readable detail. Validation errors use an array; typed errors use a string. oneOf: - type: string - type: array items: type: string example: error: bad_cursor detail: cursor is invalid or belongs to a different search NewsItem: type: object additionalProperties: false required: - id - title - url - source - description - image_url - authors - language - category - published_at - collected_at - content - content_available - content_truncated - is_update - relevance_score properties: id: type: string format: uuid description: Stable Clair record ID. title: type: string url: type: string format: uri description: Publisher URL and source of record. source: $ref: '#/components/schemas/NewsSource' description: type: string nullable: true maxLength: 1000 description: >- Publisher-provided summary or normalized short description, when available. image_url: type: string format: uri nullable: true description: Publisher-provided representative image URL, when available. authors: type: array maxItems: 10 description: Normalized publisher bylines. Empty when unavailable. items: type: string maxLength: 200 language: type: string description: >- BCP 47-style primary language code. The current public corpus is English. example: en category: type: string description: >- Deterministic publisher-section category; `general` means no narrower category was established. enum: - general - world - politics - business - technology - science - health - sports - entertainment - environment published_at: type: string format: date-time description: Publisher time, rendered with PostgreSQL microsecond precision. collected_at: type: string format: date-time description: >- When Clair collected this record, rendered with PostgreSQL microsecond precision. content: type: string nullable: true maxLength: 2000 description: >- Bounded cleaned snippet, feed excerpt fallback, or null. Clair does not expose a full-article archive. content_available: type: boolean description: Whether `content` is present. content_truncated: type: boolean description: Whether the returned snippet was capped at 2,000 characters. is_update: type: boolean description: Whether this record is a later revision of the same publisher URL. relevance_score: type: number format: double minimum: 0 maximum: 1 nullable: true description: >- Query-local text ranking signal, not a probability. Null when `q` is absent. NewsSource: type: object additionalProperties: false required: - name properties: name: type: string description: Exact publisher name. securitySchemes: rapidApiKey: type: apiKey in: header name: X-RapidAPI-Key description: >- Your RapidAPI subscription key. Also send `X-RapidAPI-Host: clair-news-api.p.rapidapi.com`. ````