openapi: 3.0.3
info:
  title: Mediastack News API
  description: |
    Mediastack is a free, simple REST API for live, historical, and blog news articles
    aggregated from over 7,500 news sources across more than 50 countries and 13 languages.
    Operated by apilayer, mediastack exposes JSON endpoints for news search, news source
    discovery, and date-bounded historical news retrieval.
  version: '1.0.0'
  contact:
    name: Mediastack Support
    url: https://mediastack.com/contact
  license:
    name: Proprietary
    url: https://mediastack.com/terms
  x-api-name: mediastack
  x-provider: apilayer
servers:
  - url: https://api.mediastack.com/v1
    description: Production HTTP base URL (Free plan and above)
  - url: https://api.mediastack.com/v1
    description: Production HTTPS base URL (Standard plan and above)
security:
  - ApiKeyAuth: []
tags:
  - name: News
    description: Live and historical news articles from global publishers.
  - name: Sources
    description: Discovery of supported news sources, publishers, and blogs.
paths:
  /news:
    get:
      tags:
        - News
      summary: Search Live News Articles
      description: |
        Retrieve live, real-time news articles aggregated from thousands of publishers worldwide.
        Filter by source, category, country, language, keywords, and date. Supports pagination
        through limit/offset. The `date` parameter enables historical lookups on paid plans.
      operationId: searchNews
      parameters:
        - $ref: '#/components/parameters/AccessKey'
        - name: sources
          in: query
          description: Comma-separated list of source identifiers to include or exclude (prefix with `-` to exclude).
          required: false
          schema:
            type: string
          example: cnn,bbc,-techcrunch
        - name: categories
          in: query
          description: Comma-separated list of categories to include or exclude (prefix with `-` to exclude).
          required: false
          schema:
            type: string
            enum:
              - general
              - business
              - entertainment
              - health
              - science
              - sports
              - technology
          example: business,technology
        - name: countries
          in: query
          description: Comma-separated list of ISO 3166-1 alpha-2 country codes to include or exclude.
          required: false
          schema:
            type: string
          example: us,gb,de
        - name: languages
          in: query
          description: Comma-separated list of ISO 639-1 language codes to include or exclude.
          required: false
          schema:
            type: string
            enum:
              - ar
              - de
              - en
              - es
              - fr
              - he
              - it
              - nl
              - 'no'
              - pt
              - ru
              - se
              - zh
          example: en,de
        - name: keywords
          in: query
          description: Free-text keywords to search across article title, description, and body.
          required: false
          schema:
            type: string
          example: climate change
        - name: date
          in: query
          description: |
            Filter by publication date or date range (paid plans only).
            Single date `YYYY-MM-DD` or range `YYYY-MM-DD,YYYY-MM-DD`.
          required: false
          schema:
            type: string
            pattern: '^\d{4}-\d{2}-\d{2}(,\d{4}-\d{2}-\d{2})?$'
          example: '2026-05-01,2026-05-28'
        - name: sort
          in: query
          description: Sort order for results.
          required: false
          schema:
            type: string
            enum:
              - published_desc
              - published_asc
              - popularity
            default: published_desc
        - name: limit
          in: query
          description: Number of results per page (max 100).
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: offset
          in: query
          description: Pagination offset.
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Paginated list of news articles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /sources:
    get:
      tags:
        - Sources
      summary: List News Sources
      description: |
        Retrieve the catalog of news sources, publishers, and blogs indexed by mediastack.
        Filter by search keyword, country, language, or category to narrow the catalog.
      operationId: listSources
      parameters:
        - $ref: '#/components/parameters/AccessKey'
        - name: search
          in: query
          description: Free-text search across source name and URL.
          required: false
          schema:
            type: string
        - name: countries
          in: query
          description: Comma-separated list of ISO 3166-1 alpha-2 country codes.
          required: false
          schema:
            type: string
        - name: languages
          in: query
          description: Comma-separated list of ISO 639-1 language codes.
          required: false
          schema:
            type: string
        - name: categories
          in: query
          description: Comma-separated list of categories.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Paginated list of news sources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourcesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: access_key
      description: |
        Mediastack uses a single static API access key passed as a query parameter
        (`access_key=YOUR_KEY`). Keys are issued from the mediastack dashboard.
  parameters:
    AccessKey:
      name: access_key
      in: query
      required: true
      description: Mediastack API access key.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid API access key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Function not allowed on current plan (e.g. historical data on Free).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Monthly request quota exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    NewsResponse:
      type: object
      required:
        - pagination
        - data
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        data:
          type: array
          items:
            $ref: '#/components/schemas/NewsArticle'
    SourcesResponse:
      type: object
      required:
        - pagination
        - data
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Source'
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          example: 25
        offset:
          type: integer
          example: 0
        count:
          type: integer
          description: Number of records returned in the current page.
          example: 25
        total:
          type: integer
          description: Total records matching the query.
          example: 10342
    NewsArticle:
      type: object
      properties:
        author:
          type: string
          nullable: true
          description: Article byline / author when available.
          example: Jane Doe
        title:
          type: string
          example: Global Markets Rally on Easing Inflation Data
        description:
          type: string
          nullable: true
          example: Equities advanced after inflation data came in softer than expected.
        url:
          type: string
          format: uri
          example: https://example.com/markets-rally
        source:
          type: string
          description: Display name of the publisher.
          example: CNN
        image:
          type: string
          format: uri
          nullable: true
          example: https://example.com/img/markets.jpg
        category:
          type: string
          enum:
            - general
            - business
            - entertainment
            - health
            - science
            - sports
            - technology
          example: business
        language:
          type: string
          description: ISO 639-1 language code.
          example: en
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: us
        published_at:
          type: string
          format: date-time
          example: '2026-05-28T14:32:00+00:00'
    Source:
      type: object
      properties:
        id:
          type: string
          description: Stable source identifier.
          example: cnn
        name:
          type: string
          example: CNN
        category:
          type: string
          example: general
        country:
          type: string
          example: us
        language:
          type: string
          example: en
        url:
          type: string
          format: uri
          example: https://www.cnn.com
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: invalid_access_key
            message:
              type: string
              example: 'You have not supplied a valid API Access Key.'
            context:
              type: object
              additionalProperties: true
              nullable: true