swagger: '2.0'
basePath: /svc/topstories/v2
host: api.nytimes.com
schemes:
  - https
info:
  version: 2.0.0
  title: Top Stories
  description: |
    The Top Stories API returns an array of articles currently on the specified section (arts, business, ...).

    ```
    /{section}.json
    ```

    Use home to get articles currently on the homepage.

    ```
    /home.json
    ```

    The possible section value are: _arts, automobiles, books, business, fashion, food, health, home, insider, magazine, movies, national, nyregion, obituaries, opinion, politics, realestate, science, sports, sundayreview, technology, theater, tmagazine, travel, upshot, and world_.

    ## Example Call
    ```
    https://api.nytimes.com/svc/topstories/v2/science.json?api-key=yourkey
    ```

produces:
  - application/json
security:
  - apikey: []
paths:
  '/{section}.json':
    get:
      summary: Top Stories
      description: |
        The Top Stories API returns an array of articles currently on the specified section.
      parameters:
        - name: section
          in: path
          description: The section the story appears in.
          required: true
          type: string
          default: home
          enum:
            - arts
            - automobiles
            - books
            - business
            - fashion
            - food
            - health
            - home
            - insider
            - magazine
            - movies
            - national
            - nyregion
            - obituaries
            - opinion
            - politics
            - realestate
            - science
            - sports
            - sundayreview
            - technology
            - theater
            - tmagazine
            - travel
            - upshot
            - world
      tags:
        - Stories
      responses:
        '200':
          description: An array of articles.
          schema:
            type: object
            properties:
              status:
                type: string
              copyright:
                type: string
              section:
                type: string
              last_updated:
                type: string
              num_results:
                type: integer
              results:
                type: array
                items:
                  $ref: '#/definitions/Article'
        '401':
          description: Unauthorized request.  Make sure api-key is set.
        '429':
          description: Too many requests.  You reached your per minute or per day rate limit.
definitions:
  Article:
    type: object
    properties:
      section:
        type: string
      subsection:
        type: string
      title:
        type: string
      abstract:
        type: string
      url:
        type: string
      byline:
        type: string
      item_type:
        type: string
      updated_date:
        type: string
      created_date:
        type: string
      published_date:
        type: string
      material_type_facet:
        type: string
      kicker:
        type: string
      des_facet:
        type: array
        items:
          type: string
      org_facet:
        type: array
        items:
          type: string
      per_facet:
        type: array
        items:
          type: string
      geo_facet:
        type: array
        items:
          type: string
      multimedia:
        type: array
        items:
          type: object
          properties:
            url:
              type: string
            format:
              type: string
            height:
              type: integer
            width:
              type: integer
            type:
              type: string
            subtype:
              type: string
            caption:
              type: string
            copyright:
              type: string
      short_url:
        type: string
securityDefinitions:
  apikey:
    type: apiKey
    name: api-key
    in: query