openapi: 3.0.1
info:
  title: The New York Times 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/review, business, fashion, food, health, home, insider, magazine, movies, nyregion, obituaries, opinion, politics, realestate, science, sports, sundayreview, technology, theater, t-magazine, travel, upshot, us, and world_.

    ## Example Calls
    ```
    https://api.nytimes.com/svc/topstories/v2/arts.json?api-key=yourkey
    https://api.nytimes.com/svc/topstories/v2/home.json?api-key=yourkey
    https://api.nytimes.com/svc/topstories/v2/science.json?api-key=yourkey
    https://api.nytimes.com/svc/topstories/v2/us.json?api-key=yourkey
    https://api.nytimes.com/svc/topstories/v2/world.json?api-key=yourkey
    ```
  version: 2.0.0
servers:
  - url: https://api.nytimes.com/svc/topstories/v2
security:
  - apikey: []
paths:
  /{section}.json:
    get:
      tags:
        - Stories
      summary: The New York Times 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
          schema:
            type: string
            default: home
            enum:
              - arts
              - automobiles
              - books/review
              - business
              - fashion
              - food
              - health
              - home
              - insider
              - magazine
              - movies
              - nyregion
              - obituaries
              - opinion
              - politics
              - realestate
              - science
              - sports
              - sundayreview
              - technology
              - theater
              - t-magazine
              - travel
              - upshot
              - us
              - world
      responses:
        "200":
          description: An array of articles.
          content:
            application/json:
              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: '#/components/schemas/Article'
        "401":
          description: Unauthorized request.  Make sure api-key is set.
          content: {}
        "429":
          description: Too many requests.  You reached your per minute or per day rate limit.
          content: {}
components:
  schemas:
    Article:
      type: object
      properties:
        section:
          type: string
        subsection:
          type: string
        title:
          type: string
        abstract:
          type: string
        url:
          type: string
        uri:
          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
  securitySchemes:
    apikey:
      type: apiKey
      name: api-key
      in: query
tags:
  - name: Stories