openapi: 3.0.0
servers:
  - url: http://api.nytimes.com/svc/topstories/v2
  - url: https://api.nytimes.com/svc/topstories/v2
info:
  description: The Top Stories API provides lists of articles and associated images by section.
  termsOfService: http://developer.nytimes.com/tou
  title: Top Stories
  version: 2.0.0
  x-apiClientRegistration:
    url: http://developer.nytimes.com/signup
  x-apisguru-categories:
    - media
    - open_data
  x-logo:
    url: https://static01.nyt.com/images/icons/t_logo_291_black.png
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nytimes/public_api_specs/master/top_stories/top_stories_v2.json
      version: "3.0"
  x-providerName: nytimes.com
  x-serviceName: top_stories
externalDocs:
  url: http://developer.nytimes.com/
security:
  - apikey: []
paths:
  /{section}.{format}:
    get:
      description: |
        The Top Stories API returns a list of articles and associated images currently on the specified section.  Support JSON and JSONP.
      parameters:
        - description: The section the story appears in.
          in: path
          name: section
          required: true
          schema:
            enum:
              - home
              - opinion
              - world
              - national
              - politics
              - upshot
              - nyregion
              - business
              - technology
              - science
              - health
              - sports
              - arts
              - books
              - movies
              - theater
              - sundayreview
              - fashion
              - tmagazine
              - food
              - travel
              - magazine
              - realestate
              - automobiles
              - obituaries
              - insider
            type: string
          x-consoleDefault: home
        - description: if this is JSONP or JSON
          in: path
          name: format
          required: true
          schema:
            enum:
              - json
              - jsonp
            type: string
          x-consoleDefault: json
        - description: |
            The name of the function the API call results will be passed to. Required when using JSONP. This parameter has only one valid value per section. The format is {section_name}TopStoriesCallback.
          in: query
          name: callback
          required: false
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  results:
                    items:
                      $ref: "#/components/schemas/Article"
                    type: array
                type: object
          description: An array of articles
      summary: Top Stories
      tags:
        - Stories
components:
  schemas:
    Article:
      properties:
        abstract:
          type: string
        byline:
          type: string
        created_date:
          type: string
        des_facet:
          items:
            type: string
          type: array
        geo_facet:
          items:
            type: string
          type: array
        item_type:
          type: string
        kicker:
          type: string
        material_type_facet:
          type: string
        multimedia:
          items:
            properties:
              caption:
                type: string
              copyright:
                type: string
              format:
                type: string
              height:
                type: integer
              subtype:
                type: string
              type:
                type: string
              url:
                type: string
              width:
                type: integer
            type: object
          type: array
        org_facet:
          items:
            type: string
          type: array
        per_facet:
          items:
            type: string
          type: array
        published_date:
          type: string
        related_urls:
          items:
            properties:
              suggested_link_text:
                type: string
              url:
                type: string
            type: object
          type: array
        section:
          type: string
        short_url:
          type: string
        subsection:
          type: string
        thumbnail_standard:
          type: string
        title:
          type: string
        updated_date:
          type: string
        url:
          type: string
      type: object
  securitySchemes:
    apikey:
      in: query
      name: api-key
      type: apiKey
