openapi: 3.0.0
servers:
  - url: http://api.nytimes.com/svc/news/v3
  - url: https://api.nytimes.com/svc/news/v3
info:
  description: With the Times Newswire API, you can get links and metadata for Times articles and blog posts as soon as they are published on NYTimes.com. The Times Newswire API provides an up-to-the-minute stream of published items.
  termsOfService: http://developer.nytimes.com/tou
  title: Times Newswire API
  version: 3.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/timeswire/timeswire_v3.json
      version: "3.0"
  x-providerName: nytimes.com
  x-serviceName: timeswire
externalDocs:
  url: http://developer.nytimes.com/
security:
  - apikey: []
paths:
  /content.json:
    get:
      parameters:
        - description: The complete URL of a specific news item, URL-encoded or backslash-escaped
          in: query
          name: url
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      $ref: "#/components/schemas/Article"
                    type: array
                  status:
                    type: string
                type: object
          description: An array of Articles
  /content/{source}/{section}.json:
    get:
      parameters:
        - description: |
            Limits the set of items by originating source

            all = items from both The New York Times and The International New York Times
            nyt = New York Times items only
            iht = International New York Times items only
          in: path
          name: source
          required: true
          schema:
            enum:
              - all
              - nyt
              - iht
            type: string
          x-consoleDefault: all
        - description: |
            Limits the set of items by one or more sections
            all | One or more section names, separated by semicolons

             To get all sections, specify all. To get a particular section or sections, use the section names returned by this request:
             http://api.nytimes.com/svc/news/v3/content/section-list.json
          in: path
          name: section
          required: true
          schema:
            type: string
          x-consoleDefault: all
        - description: Limits the number of results, between 1 and 20
          in: query
          name: limit
          required: false
          schema:
            default: 20
            type: integer
        - description: Sets the starting point of the result set
          in: query
          name: offset
          required: false
          schema:
            default: 0
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      $ref: "#/components/schemas/Article"
                    type: array
                  status:
                    type: string
                type: object
          description: An array of Articles
  /content/{source}/{section}/{time-period}.json:
    get:
      parameters:
        - description: |
            Limits the set of items by originating source

            all = items from both The New York Times and The International New York Times
            nyt = New York Times items only
            iht = International New York Times items only
          in: path
          name: source
          required: true
          schema:
            enum:
              - all
              - nyt
              - iht
            type: string
        - description: |
            Limits the set of items by one or more sections
            all | One or more section names, separated by semicolons

             To get all sections, specify all. To get a particular section or sections, use the section names returned by this request:
             http://api.nytimes.com/svc/news/v3/content/section-list.json
          in: path
          name: section
          required: true
          schema:
            type: string
        - description: Limits the set of items by time published, integer in number of hours
          in: path
          name: time-period
          required: true
          schema:
            type: integer
        - description: Limits the number of results, between 1 and 20
          in: query
          name: limit
          required: false
          schema:
            default: 20
            type: integer
        - description: Sets the starting point of the result set
          in: query
          name: offset
          required: false
          schema:
            default: 0
            type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      $ref: "#/components/schemas/Article"
                    type: array
                  status:
                    type: string
                type: object
          description: An array of Articles
components:
  schemas:
    Article:
      properties:
        abstract:
          type: string
        blog_name:
          type: string
        byline:
          type: string
        created_date:
          type: string
        des_facet:
          items:
            type: string
          type: array
        geo_facet:
          items:
            type: string
          type: array
        headline:
          type: string
        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:
          type: string
        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
        source:
          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
