openapi: 3.0.3
info:
  title: News Everything API
  description: 'NewsAPI is a simple, easy-to-use REST API that returns JSON metadata for news articles and breaking headlines published by over 80,000 worldwide sources and blogs. The API supports full-text keyword search across hundreds of millions of articles, filtering by source domain, language, date range, and sorting by relevance or publication date. A dedicated top-headlines endpoint delivers live breaking news by country and category. Developers authenticate via an API key passed as a query parameter or HTTP header.

    '
  version: '2'
  contact:
    name: NewsAPI Support
    url: https://newsapi.org/
  termsOfService: https://newsapi.org/terms
  license:
    name: Proprietary
    url: https://newsapi.org/terms
servers:
- url: https://newsapi.org/v2
  description: Production server
security:
- apiKeyHeader: []
- apiKeyQuery: []
- bearerAuth: []
tags:
- name: Everything
  description: Search all articles from all sources
paths:
  /everything:
    get:
      operationId: getEverything
      summary: Search all articles
      description: 'Search through millions of articles from over 80,000 large and small news sources and blogs. This endpoint suits article discovery and analysis. Supports keyword search, source filtering, domain filtering, language selection, date-range queries, and result sorting.

        '
      tags:
      - Everything
      parameters:
      - name: q
        in: query
        description: 'Keywords or phrases to search for in the article title and body. Surround phrases with quotes for exact match. Prepend words or phrases that must appear with a + symbol. Prepend words that must not appear with a - symbol. The complete value must be URL-encoded. Max length: 500 characters.

          '
        required: false
        schema:
          type: string
          maxLength: 500
      - name: searchIn
        in: query
        description: 'The fields to restrict your q search to. Multiple options can be specified as a comma-separated string.

          '
        required: false
        schema:
          type: string
          enum:
          - title
          - description
          - content
      - name: sources
        in: query
        description: 'A comma-separated string of identifiers (maximum 20) for the news sources or blogs you want headlines from. Use the /top-headlines/sources endpoint to locate these programmatically. Note: you can''t mix this param with the country or category params.

          '
        required: false
        schema:
          type: string
      - name: domains
        in: query
        description: 'A comma-separated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to restrict the search to.

          '
        required: false
        schema:
          type: string
      - name: excludeDomains
        in: query
        description: 'A comma-separated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to remove from the results.

          '
        required: false
        schema:
          type: string
      - name: from
        in: query
        description: 'A date and optional time for the oldest article allowed. This should be in ISO 8601 format (e.g. 2024-01-01 or 2024-01-01T00:00:00).

          '
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        description: 'A date and optional time for the newest article allowed. This should be in ISO 8601 format (e.g. 2024-01-01 or 2024-01-01T00:00:00).

          '
        required: false
        schema:
          type: string
          format: date-time
      - name: language
        in: query
        description: 'The 2-letter ISO-639-1 code of the language you want to get headlines for.

          '
        required: false
        schema:
          type: string
          enum:
          - ar
          - de
          - en
          - es
          - fr
          - he
          - it
          - nl
          - 'no'
          - pt
          - ru
          - sv
          - ud
          - zh
      - name: sortBy
        in: query
        description: 'The order to sort the articles in. Possible options: relevancy, popularity, publishedAt. relevancy = articles more closely related to q come first. popularity = articles from popular sources and publishers come first. publishedAt = newest articles come first.

          '
        required: false
        schema:
          type: string
          enum:
          - relevancy
          - popularity
          - publishedAt
          default: publishedAt
      - name: pageSize
        in: query
        description: 'The number of results to return per page. 20 is the default, 100 is the maximum.

          '
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      - name: page
        in: query
        description: 'Use this to page through the results. Default is 1.

          '
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: apiKey
        in: query
        description: Your API key. Alternatively provide via the X-Api-Key header.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response with articles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticlesResponse'
              example:
                status: ok
                totalResults: 4215
                articles:
                - source:
                    id: techcrunch
                    name: TechCrunch
                  author: John Smith
                  title: Apple Reports Record Quarterly Earnings
                  description: Apple Inc. reported record quarterly earnings today...
                  url: https://techcrunch.com/2024/01/15/apple-earnings
                  urlToImage: https://techcrunch.com/images/apple-earnings.jpg
                  publishedAt: '2024-01-15T18:00:00Z'
                  content: Apple Inc. reported record quarterly earnings today, beating analyst expectations... [+4500 chars]
        '400':
          description: Bad request - missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests - rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Source:
      type: object
      description: The news source or blog that an article originated from
      properties:
        id:
          type: string
          nullable: true
          description: The identifier of the news source. You can use this with our other endpoints.
          example: techcrunch
        name:
          type: string
          description: The display name of the news source.
          example: TechCrunch
    Article:
      type: object
      description: A news article
      properties:
        source:
          $ref: '#/components/schemas/Source'
        author:
          type: string
          nullable: true
          description: The author of the article.
          example: Jane Doe
        title:
          type: string
          description: The headline or title of the article.
          example: Apple Reports Record Quarterly Earnings
        description:
          type: string
          nullable: true
          description: A description or snippet from the article.
          example: Apple Inc. reported record quarterly earnings today, beating analyst expectations.
        url:
          type: string
          format: uri
          description: The direct URL to the article.
          example: https://techcrunch.com/2024/01/15/apple-earnings
        urlToImage:
          type: string
          format: uri
          nullable: true
          description: The URL to a relevant image for the article.
          example: https://techcrunch.com/images/apple-earnings.jpg
        publishedAt:
          type: string
          format: date-time
          description: The date and time that the article was published, in UTC (+000).
          example: '2024-01-15T18:00:00Z'
        content:
          type: string
          nullable: true
          description: 'The unformatted content of the article, where available. This is truncated to 200 chars. A link to the full article is always in the url parameter.

            '
          example: Apple Inc. reported record quarterly earnings today, beating analyst expectations... [+4500 chars]
    ArticlesResponse:
      type: object
      description: Response containing a list of articles
      properties:
        status:
          type: string
          description: If the request was successful or not. Options are ok and error.
          enum:
          - ok
          - error
          example: ok
        totalResults:
          type: integer
          description: The total number of results available for your request.
          example: 4215
        articles:
          type: array
          description: The results of the request.
          items:
            $ref: '#/components/schemas/Article'
    ErrorResponse:
      type: object
      description: Error response
      properties:
        status:
          type: string
          description: Always "error" for error responses.
          enum:
          - error
          example: error
        code:
          type: string
          description: A short code identifying the type of error returned.
          enum:
          - apiKeyDisabled
          - apiKeyExhausted
          - apiKeyInvalid
          - apiKeyMissing
          - parameterInvalid
          - parametersMissing
          - rateLimited
          - sourcesTooMany
          - sourceDoesNotExist
          - unexpectedError
          example: apiKeyInvalid
        message:
          type: string
          description: A fuller description of the error, usually including how to fix it.
          example: Your API key hasn't been entered correctly. Double check it and try again.
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key passed via X-Api-Key HTTP header
    apiKeyQuery:
      type: apiKey
      in: query
      name: apiKey
      description: API key passed as a query parameter
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key passed as a Bearer token. Note: the Bearer prefix is optional and the key should NOT be base64 encoded.

        '