NewsAPI Top Headlines API

openapi: 3.0.3
info:
  title: News Everything Top Headlines 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: Top Headlines
  description: Get live top and breaking headlines
paths:
  /top-headlines:
    get:
      operationId: getTopHeadlines
      summary: Get top headlines
      description: 'Provides live top and breaking headlines for a country, specific category in a country, single source, multiple sources, or a query. You can use this endpoint to get breaking news programmatically and use it to fuel your news-driven apps and news feeds.

        '
      tags:
      - Top Headlines
      parameters:
      - name: country
        in: query
        description: 'The 2-letter ISO 3166-1 code of the country you want to get headlines for. Note: you can''t mix this param with the sources param.

          '
        required: false
        schema:
          type: string
          enum:
          - ae
          - ar
          - at
          - au
          - be
          - bg
          - br
          - ca
          - ch
          - cn
          - co
          - cu
          - cz
          - de
          - eg
          - fr
          - gb
          - gr
          - hk
          - hu
          - id
          - ie
          - il
          - in
          - it
          - jp
          - kr
          - lt
          - lv
          - ma
          - mx
          - my
          - ng
          - nl
          - 'no'
          - nz
          - ph
          - pl
          - pt
          - ro
          - rs
          - ru
          - sa
          - se
          - sg
          - si
          - sk
          - th
          - tr
          - tw
          - ua
          - us
          - ve
          - za
      - name: category
        in: query
        description: 'The category you want to get headlines for. Note: you can''t mix this param with the sources param.

          '
        required: false
        schema:
          type: string
          enum:
          - business
          - entertainment
          - general
          - health
          - science
          - sports
          - technology
      - name: sources
        in: query
        description: 'A comma-separated string of identifiers for the news sources or blogs you want headlines from. Use the /top-headlines/sources endpoint to locate these. Note: you can''t mix this param with the country or category params.

          '
        required: false
        schema:
          type: string
      - name: q
        in: query
        description: Keywords or a phrase to search for.
        required: false
        schema:
          type: string
      - name: pageSize
        in: query
        description: The number of results to return per page. Default is 20, maximum is 100.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - 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 top headlines
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticlesResponse'
              example:
                status: ok
                totalResults: 38
                articles:
                - source:
                    id: bbc-news
                    name: BBC News
                  author: BBC News
                  title: US economy shows strong growth in Q4
                  description: The US economy grew at an annualized rate of 3.3%...
                  url: https://www.bbc.com/news/business-12345678
                  urlToImage: https://ichef.bbci.co.uk/news/1024/branded_news/12345.jpg
                  publishedAt: '2024-01-26T14:00:00Z'
                  content: The US economy grew at an annualized rate of 3.3% in the fourth quarter... [+2500 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.

        '