openapi: 3.0.1
info:
  contact:
    email: support@aylien.com
    name: API support
    url: https://newsapi.aylien.com/
  description: 'The AYLIEN News API is the most powerful way of sourcing, searching and syndicating analyzed and enriched news content. It is accessed by sending HTTP requests to our server, which returns information to your client.

    '
  termsOfService: https://newsapi.aylien.com/tos
  title: AYLIEN News Absa cluster API
  version: '3.0'
servers:
- url: https://api.aylien.com/news
tags:
- name: cluster
paths:
  /clusters:
    get:
      tags:
      - cluster
      description: 'The clusters endpoint is used to return clusters based on parameters you set in your query.

        '
      operationId: listClusters
      parameters:
      - description: 'This parameter is used for finding clusters by cluster id.

          '
        explode: true
        in: query
        name: id[]
        schema:
          items:
            format: int64
            type: integer
          nullable: true
          type: array
        style: form
      - description: 'This parameter is used for excluding clusters by cluster id.

          '
        explode: true
        in: query
        name: '!id[]'
        schema:
          items:
            format: int64
            type: integer
          nullable: true
          type: array
        style: form
      - description: 'This parameter is used for finding clusters with more than or equal to a specific amount of stories associated with them.

          '
        in: query
        name: story_count.min
        schema:
          exclusiveMinimum: true
          format: int32
          minimum: 0
          nullable: true
          type: integer
      - description: 'This parameter is used for finding clusters with less than or equal to a specific amount of stories associated with them.

          '
        in: query
        name: story_count.max
        schema:
          exclusiveMinimum: true
          format: int32
          minimum: 0
          nullable: true
          type: integer
      - description: 'This parameter is used for finding clusters whose creation time is greater than the specified value. [Here](https://newsapi.aylien.com/docs/working-with-dates) you can find more information about how [to work with dates](https://newsapi.aylien.com/docs/working-with-dates).

          '
        in: query
        name: time.start
        schema:
          nullable: true
          type: string
      - description: 'This parameter is used for finding clusters whose creation time is less than the specified value. [Here](https://newsapi.aylien.com/docs/working-with-dates) you can find more information about how [to work with dates](https://newsapi.aylien.com/docs/working-with-dates).

          '
        in: query
        name: time.end
        schema:
          nullable: true
          type: string
      - description: 'This parameter is used for finding clusters whose publication date of its earliest story is greater than the specified value. [Here](https://newsapi.aylien.com/docs/working-with-dates) you can find more information about how [to work with dates](https://newsapi.aylien.com/docs/working-with-dates).

          '
        in: query
        name: earliest_story.start
        schema:
          nullable: true
          type: string
      - description: 'This parameter is used for finding clusters whose publication date of its earliest story is less than the specified value. [Here](https://newsapi.aylien.com/docs/working-with-dates) you can find more information about how [to work with dates](https://newsapi.aylien.com/docs/working-with-dates).

          '
        in: query
        name: earliest_story.end
        schema:
          nullable: true
          type: string
      - description: 'This parameter is used for finding clusters whose publication date of its latest story is greater than the specified value. [Here](https://newsapi.aylien.com/docs/working-with-dates) you can find more information about how [to work with dates](https://newsapi.aylien.com/docs/working-with-dates).

          '
        in: query
        name: latest_story.start
        schema:
          nullable: true
          type: string
      - description: 'This parameter is used for finding clusters whose publication date of its latest story is less than the specified value. [Here](https://newsapi.aylien.com/docs/working-with-dates) you can find more information about how [to work with dates](https://newsapi.aylien.com/docs/working-with-dates).

          '
        in: query
        name: latest_story.end
        schema:
          nullable: true
          type: string
      - description: 'This parameter is used for finding clusters belonging to a specific country. It supports [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes. [Here](https://newsapi.aylien.com/docs/working-with-locations) you can find more information about how [to work with locations](https://newsapi.aylien.com/docs/working-with-locations).

          '
        explode: true
        in: query
        name: location.country
        schema:
          items:
            type: string
          nullable: true
          type: array
        style: form
      - description: 'This parameter is used for excluding clusters belonging to a specific country. It supports [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes. [Here](https://newsapi.aylien.com/docs/working-with-locations) you can find more information about how [to work with locations](https://newsapi.aylien.com/docs/working-with-locations).

          '
        explode: true
        in: query
        name: '!location.country'
        schema:
          items:
            type: string
          nullable: true
          type: array
        style: form
      - description: This parameter is used for specifying return fields.
        explode: true
        in: query
        name: return[]
        schema:
          items:
            enum:
            - id
            - time
            - summary
            - category
            - story_count
            - earliest_story
            - latest_story
            - representative_story
            - location_country
            type: string
          nullable: true
          type: array
        style: form
      - description: 'This parameter is used for changing the order column of the results. You can read about sorting results [here](https://newsapi.aylien.com/docs/sorting-results).

          '
        in: query
        name: sort_by
        schema:
          default: published_at
          enum:
          - time
          - story_count
          - earliest_story
          - latest_story
          nullable: true
          type: string
      - description: 'This parameter is used for changing the order direction of the result. You can read about sorting results [here](https://newsapi.aylien.com/docs/sorting-results).

          '
        in: query
        name: sort_direction
        schema:
          default: desc
          enum:
          - asc
          - desc
          nullable: true
          type: string
      - description: 'This parameter is used for finding a specific page. You can read more about pagination of results [here](https://newsapi.aylien.com/docs/pagination-of-results).

          '
        in: query
        name: cursor
        schema:
          default: '*'
          nullable: true
          type: string
      - description: 'This parameter is used for specifying number of items in each page You can read more about pagination of results [here](https://newsapi.aylien.com/docs/pagination-of-results)

          '
        in: query
        name: per_page
        schema:
          default: 10
          format: int32
          maximum: 100
          minimum: 1
          nullable: true
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/clusters'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
            text/xml:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
            text/xml:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
            text/xml:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
            text/xml:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Too Many Requests
          headers:
            X-RateLimit-Limit:
              description: The number of allowed requests in the current period.
              schema:
                format: int32
                type: integer
            X-RateLimit-Remaining:
              description: The number of remaining requests in the current period.
              schema:
                format: int32
                type: integer
            X-RateLimit-Reset:
              description: 'The remaining window before the rate limit resets in UTC [epoch seconds](https://en.wikipedia.org/wiki/Unix_time).

                '
              schema:
                format: int64
                type: integer
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
            text/xml:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Internal Server Error
      security:
      - app_id: []
      - app_key: []
      summary: List Clusters
components:
  schemas:
    Location:
      properties:
        city:
          description: The city of the location
          type: string
        country:
          description: 'The country code of the location. It supports [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes.

            '
          type: string
        state:
          description: The state of the location
          type: string
      type: object
    ErrorLinks:
      properties:
        about:
          type: string
        docs:
          type: string
      type: object
    Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/Error'
          type: array
      type: object
    Clusters:
      properties:
        cluster_count:
          description: The total number of clusters
          format: int64
          type: integer
        clusters:
          description: An array of clusters
          items:
            $ref: '#/components/schemas/Cluster'
          type: array
        next_page_cursor:
          description: The next page cursor
          type: string
      type: object
    Error:
      properties:
        code:
          type: string
        detail:
          type: string
        id:
          type: string
        links:
          $ref: '#/components/schemas/ErrorLinks'
        status:
          type: string
        title:
          type: string
      type: object
    Cluster:
      properties:
        earliest_story:
          description: Publication date of the earliest story in cluster
          format: date-time
          type: string
        id:
          description: ID of the cluster which is a unique identification
          format: int64
          type: integer
        latest_story:
          description: Publication date of the latest story in cluster
          format: date-time
          type: string
        location:
          $ref: '#/components/schemas/Location'
        representative_story:
          $ref: '#/components/schemas/RepresentativeStory'
        story_count:
          description: Number of stories associated with the cluster
          format: int32
          type: integer
        time:
          description: Time of the event
          format: date-time
          type: string
      type: object
    RepresentativeStory:
      properties:
        id:
          description: ID of the story which is a unique identification
          format: int64
          type: integer
        permalink:
          description: The story permalink URL
          type: string
        published_at:
          description: Published date of the story
          format: date-time
          type: string
        title:
          description: Title of the story
          type: string
      type: object
  responses:
    clusters:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Clusters'
        text/xml:
          schema:
            $ref: '#/components/schemas/Clusters'
      description: An object including an array of clusters
      headers:
        X-RateLimit-Limit:
          description: The number of allowed requests in the current period.
          schema:
            format: int32
            type: integer
        X-RateLimit-Remaining:
          description: The number of remaining requests in the current period.
          schema:
            format: int32
            type: integer
        X-RateLimit-Reset:
          description: 'The remaining window before the rate limit resets in UTC [epoch seconds](https://en.wikipedia.org/wiki/Unix_time).

            '
          schema:
            format: int64
            type: integer
  securitySchemes:
    app_id:
      x-auth-id-alias: true
      description: 'X-AYLIEN-NewsAPI-Application-ID is the identifier of your server, script, or program with a specific application. This parameter is required if you are accessing APIs without authenticating.

        '
      in: header
      name: X-AYLIEN-NewsAPI-Application-ID
      type: apiKey
    app_key:
      x-auth-id-alias: true
      description: 'X-AYLIEN-NewsAPI-Application-Key is the secret key of your server, script, or program with a specific application. This parameter is required if you are accessing APIs without authenticating.

        '
      in: header
      name: X-AYLIEN-NewsAPI-Application-Key
      type: apiKey
x-group-parameters: true