openapi: 3.0.1
info:
  title: Top Stories API
  version: '1.0'
servers:
- url: https://api.dowjones.com/
paths:
  /content/{ref}:
    get:
      tags:
      - Content
      summary: "Gets a single content by its ref ID –a DowJones Resource Name (DRN).\r\nExamples of ref ID (DRN ID): drn:content.article.BL-PENTAB-3839"
      operationId: GetContentByRef
      parameters:
      - name: ref
        in: path
        description: A reference ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/vnd.dowjones.dna+json:
              schema:
                $ref: '#/components/schemas/DnaArticleExample'
        '404':
          description: Not Found
          content:
            application/vnd.dowjones.dna+json:
              schema:
                $ref: '#/components/schemas/DnaArticleResponseNotFoundExample'
        '500':
          description: Server Error
          content:
            application/vnd.dowjones.dna+json:
              schema:
                $ref: '#/components/schemas/DnaArticleUncaughtExceptionExample'
      security:
      - Bearer: []
  /content-collections/{ref}:
    get:
      tags:
      - ContentCollections
      summary: Gets the content of an entitled content-collection by its DRN ID
      operationId: GetContentCollectionByRef
      parameters:
      - name: ref
        in: path
        description: A reference ID
        required: true
        schema:
          type: string
      - name: prepub
        in: query
        description: Specifies if search should be prepub
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/vnd.dowjones.dna+json:
              schema:
                $ref: '#/components/schemas/DnaContentCollectionExample'
      security:
      - Bearer: []
  /content-collections:
    get:
      tags:
      - ContentCollections
      summary: Gets a full list of entitled content-collection IDs
      operationId: GetCollectionIdList
      responses:
        '200':
          description: Success
          content: {}
      security:
      - Bearer: []
components:
  schemas:
    JsonApiHeader:
      type: object
      properties:
        version:
          type: string
          description: Specifies the API version
    JsonApiError:
      type: object
      properties:
        title:
          type: string
          description: Error title
        id:
          type: string
          description: Specifies the requested DRN ID
        detail:
          type: string
          description: Detailed description of the error
        status:
          type: string
          description: Error status
          enum:
          - continue
          - switchingProtocols
          - oK
          - created
          - accepted
          - nonAuthoritativeInformation
          - noContent
          - resetContent
          - partialContent
          - multipleChoices
          - ambiguous
          - movedPermanently
          - moved
          - found
          - redirect
          - seeOther
          - redirectMethod
          - notModified
          - useProxy
          - unused
          - temporaryRedirect
          - redirectKeepVerb
          - badRequest
          - unauthorized
          - paymentRequired
          - forbidden
          - notFound
          - methodNotAllowed
          - notAcceptable
          - proxyAuthenticationRequired
          - requestTimeout
          - conflict
          - gone
          - lengthRequired
          - preconditionFailed
          - requestEntityTooLarge
          - requestUriTooLong
          - unsupportedMediaType
          - requestedRangeNotSatisfiable
          - expectationFailed
          - upgradeRequired
          - internalServerError
          - notImplemented
          - badGateway
          - serviceUnavailable
          - gatewayTimeout
          - httpVersionNotSupported
        code:
          type: string
          description: Error code
    JsonApiResourceObject:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        attributes:
          type: object
          properties: {}
        links:
          type: object
          properties: {}
        meta:
          type: object
          properties: {}
    ArticleMeta:
      type: object
      properties:
        properties:
          type: array
          description: ArticleMeta properties. Contains an array of JSON objects
          items:
            type: object
            properties: {}
        problems:
          type: array
          description: Problems parsing the content
          items:
            $ref: '#/components/schemas/Problem'
        codes:
          $ref: '#/components/schemas/CodeMeta'
        keywords:
          type: array
          description: Free form, unstructured tags or keywords
          items:
            type: string
        parser_version:
          $ref: '#/components/schemas/Version'
        source:
          $ref: '#/components/schemas/Source'
        original_doc_id:
          type: string
          description: The original document id of this content
        language:
          type: object
          properties:
            code:
              type: string
              description: The language code of this content
    Links:
      type: object
      properties:
        self:
          type: string
          description: Link to the DRN resource
        related:
          $ref: '#/components/schemas/Related'
    Meta:
      type: object
      properties:
        count:
          type: integer
          description: Number of records returned
          format: int32
    Source:
      type: object
      properties:
        parameter:
          type: string
          description: Specifies the source endpoint
    Problem:
      type: object
      properties:
        origin_id:
          type: string
          description: Origin ID
        type:
          type: string
          description: Problem type
        problem_xml:
          type: string
          description: Problem XML file
        timestamp:
          type: string
          description: Indicates when the problem occurred
          format: date-time
    CodeMeta:
      type: object
      properties:
        code:
          type: array
          description: Code in use
          items:
            type: string
        code_with_significance:
          type: array
          items:
            type: string
    Version:
      type: object
      properties:
        major:
          type: integer
          description: Major version number. Increments when there are significant changes that might be incompatible with previous versions
          format: int32
          readOnly: true
        minor:
          type: integer
          description: Minor version number. Increments when there are minor changes, such as bug fixes or new features
          format: int32
          readOnly: true
        build:
          type: integer
          description: Increments with each new build
          format: int32
          readOnly: true
        revision:
          type: integer
          description: Increments with each new revision
          format: int32
          readOnly: true
        major_revision:
          type: integer
          description: Increments when the article has a major revision
          format: int32
          readOnly: true
        minor_revision:
          type: integer
          description: Increments when the article has a minor revision
          format: int32
          readOnly: true
    Related:
      type: object
      properties:
        href:
          type: string
          description: Specifies the URL link
        meta:
          $ref: '#/components/schemas/Meta'
    BaseContent:
      type: object
      properties:
        type:
          type: string
          description: Type of content
        id:
          type: string
          description: ID associated with the content
        ref:
          type: string
          description: References to the content
        content:
          type: array
          description: Array of Base Content objects, which constitute the parent content
          items:
            $ref: '#/components/schemas/BaseContent'
        text:
          type: string
          description: The text corresponding to the content
        variant:
          type: string
          description: Content variation
        debug:
          type: string
          description: Debugging information
    Associations:
      type: object
      properties:
        root_id:
          type: string
          description: ID of the associated article
        parent_id:
          type: string
          description: Article parent ID
        parent_id_ref:
          type: string
          description: Article parent reference
        mantis_id:
          type: string
          description: Article Mantis ID
        editor_id:
          type: string
          description: Article editor ID
    MetaObject:
      type: object
      properties:
        properties:
          type: object
          properties: {}
        type:
          type: string
    AssociatedResource:
      type: object
    EntityResource:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        confidence:
          type: integer
        name_format:
          type: string
        name:
          type: string
        significance:
          type: string
        id:
          type: string
        type:
          type: string
    LinkResource:
      type: object
      properties:
        variant:
          type: string
        type:
          type: string
        uri:
          type: string
        id:
          type: string
    MediaResource:
      type: object
      properties:
        type:
          type: string
        media_type:
          type: string
        slug:
          type: string
        name:
          type: string
        id:
          type: string
        width:
          type: integer
        height:
          type: integer
        size_code:
          type: string
        credit:
          type: string
        caption:
          type: string
        alternate_text:
          type: string
        properties:
          type: object
          properties:
            softcrop:
              type: string
            reuse_type:
              type: string
            responsive:
              type: object
              properties:
                layout:
                  type: string
            location:
              type: string
            imphotoid:
              type: string
    AuthorResource:
      type: object
      properties:
        name:
          type: string
        id:
          type: string
        type:
          type: string
    InsetResource:
      type: object
      properties:
        type:
          type: string
        inset_type:
          type: string
        id:
          type: string
        properties:
          type: object
          properties:
            responsive:
              type: object
              properties:
                layout:
                  type: string
    DnaArticleExample:
      type: object
      properties:
        jsonapi:
          $ref: '#/components/schemas/JsonApiHeader'
        data:
          $ref: '#/components/schemas/JsonApiResourceObject_DnaArticleData_'
        links:
          type: object
          properties: {}
          description: Resource links
        meta:
          $ref: '#/components/schemas/ArticleMeta'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/JsonApiError'
    DnaContentCollectionExample:
      type: object
      properties:
        jsonapi:
          $ref: '#/components/schemas/JsonApiHeader'
        data:
          $ref: '#/components/schemas/JsonApiResourceObject_DnaContentCollection_'
        links:
          type: object
          properties: {}
          description: Resource links
        included:
          uniqueItems: true
          type: array
          description: Lists links that point to resources outside the collection
          items:
            $ref: '#/components/schemas/JsonApiResourceObject_DnaArticleData_'
        meta:
          $ref: '#/components/schemas/ArticlesMeta'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/JsonApiError'
    JsonApiResourceObject_DnaArticleData_:
      type: object
      properties:
        id:
          type: string
          description: Represents the DRN reference ID assigned to the resource
        type:
          type: string
          description: Represents the type of resource
        attributes:
          $ref: '#/components/schemas/DnaArticleData'
        links:
          type: object
          properties: {}
          description: Links object with the links related to the resource
        meta:
          type: object
          properties: {}
          description: Meta object with additional information about the resource
    JsonApiResourceObject_DnaContentCollection_:
      type: object
      properties:
        id:
          type: string
          description: Represents the DRN reference ID assigned to the resource
        type:
          type: string
          description: Represents the type of resource
        attributes:
          type: object
          properties:
            description:
              type: string
              description: Represents the name of the collection
        relationships:
          $ref: '#/components/schemas/DnaContentCollectionRelationships'
    DnaContentCollectionRelationships:
      type: object
      properties:
        articles:
          $ref: '#/components/schemas/ArticlesRelationshipsData'
        videos:
          $ref: '#/components/schemas/ArticlesRelationshipsData'
        audio:
          $ref: '#/components/schemas/ArticlesRelationshipsData'
        errors:
          $ref: '#/components/schemas/ArticlesRelationshipsData'
    ArticlesRelationshipsData:
      type: array
      items:
        $ref: '#/components/schemas/ArticlesRelationshipsDataElements'
    ArticlesRelationshipsDataElements:
      type: object
      properties:
        id:
          type: string
          description: Represents the id of the included article
        type:
          type: string
    DnaArticleData:
      type: object
      properties:
        content_type:
          type: string
          description: The type of content being returned (e.g. Article)
        associations:
          $ref: '#/components/schemas/Associations'
        authors:
          type: array
          description: An array with the author or authors of the article
          items:
            $ref: '#/components/schemas/Author'
        body:
          type: array
          description: Main article body, contains text, links, insets, and other complex objects
          items:
            $ref: '#/components/schemas/BaseContent'
        byline:
          $ref: '#/components/schemas/BaseContent'
        credit:
          $ref: '#/components/schemas/BaseContent'
        contact:
          $ref: '#/components/schemas/BaseContent'
        corrections:
          $ref: '#/components/schemas/BaseContent'
        column_name:
          type: string
          description: Column name
        copyright:
          $ref: '#/components/schemas/BaseContent'
        display_name:
          type: string
        headline:
          $ref: '#/components/schemas/Headline'
        hosted_url:
          type: string
          description: The URL of the article on the hosted domain
        id_ref:
          type: string
          description: DRN ID associated to the resource
        content_resources:
          type: array
          description: Resources comprising the content
          items:
            $ref: '#/components/schemas/AssociatedResource'
        live_date:
          type: string
          description: The date to be displayed
        live_time:
          type: string
          description: The date/time to be displayed on the article in UTC
          format: date-time
        major_revision_date:
          type: string
          description: The date/time the article has had a major revision
          format: date-time
        minor_revision:
          type: boolean
          description: Specifies if the article has had a minor revision
        modification_date:
          type: string
          description: The date the article was last updated
        modification_time:
          type: string
          description: The date/time the article was last updated in UTC
          format: date-time
        order:
          type: integer
          description: Order
          format: int32
        original_headline:
          $ref: '#/components/schemas/BaseContent'
        page:
          type: string
          description: Page where the article is displayed
        product:
          type: string
          description: The product to which the article belongs to
        publication_date:
          type: string
          description: The date the article was published
        publication_time:
          type: string
          description: The date/time the article was published in UTC
          format: date-time
        publisher:
          $ref: '#/components/schemas/Publisher'
        section_name:
          $ref: '#/components/schemas/BaseContent'
        section_type:
          type: string
          description: Section type of website, used for Ad placement and recommended stories
        seo_id:
          type: string
          description: Unique Id generated for SEO purposes. Generally these are created programmatically and are suffixed with epoch millis
        summary:
          $ref: '#/components/schemas/Summary'
        id:
          type: string
        attributes:
          type: object
          properties: {}
        errors:
          type: array
          items:
            $ref: '#/components/schemas/JsonApiError'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
    Author:
      type: object
      properties:
        full_name:
          type: string
          description: Author's full display name
        topic_id:
          type: string
          description: Topic ID
    Headline:
      type: object
      properties:
        flashline:
          $ref: '#/components/schemas/BaseContent'
        main:
          $ref: '#/components/schemas/BaseContent'
        deck:
          $ref: '#/components/schemas/BaseContent'
    Publisher:
      type: object
      properties:
        code:
          type: string
          description: Publisher code
        name:
          type: string
          description: Publisher name
        group_code:
          type: string
          description: Publisher group code
        group_name:
          type: string
          description: Publisher group name
    Summary:
      type: object
      properties:
        variant:
          type: string
          description: Summary variation
        destination_type:
          type: string
          description: Destination type variation
        pages:
          type: array
          description: List of pages that display this summary
          items:
            type: string
        byline:
          $ref: '#/components/schemas/BaseContent'
        headline:
          $ref: '#/components/schemas/Headline'
        body:
          type: array
          description: Summary body
          items:
            $ref: '#/components/schemas/BaseContent'
        related_links:
          type: array
          description: Related links
          items:
            $ref: '#/components/schemas/BaseContent'
    DnaArticleResponseNotFoundExample:
      type: object
      properties:
        title:
          type: string
          description: Error title
        id:
          type: string
          description: Article ID
        detail:
          type: string
          description: Detailed description of the error
        status:
          type: string
          description: Error status
          enum:
          - continue
          - switchingProtocols
          - oK
          - created
          - accepted
          - nonAuthoritativeInformation
          - noContent
          - resetContent
          - partialContent
          - multipleChoices
          - ambiguous
          - movedPermanently
          - moved
          - found
          - redirect
          - seeOther
          - redirectMethod
          - notModified
          - useProxy
          - unused
          - temporaryRedirect
          - redirectKeepVerb
          - badRequest
          - unauthorized
          - paymentRequired
          - forbidden
          - notFound
          - methodNotAllowed
          - notAcceptable
          - proxyAuthenticationRequired
          - requestTimeout
          - conflict
          - gone
          - lengthRequired
          - preconditionFailed
          - requestEntityTooLarge
          - requestUriTooLong
          - unsupportedMediaType
          - requestedRangeNotSatisfiable
          - expectationFailed
          - upgradeRequired
          - internalServerError
          - notImplemented
          - badGateway
          - serviceUnavailable
          - gatewayTimeout
          - httpVersionNotSupported
        code:
          type: string
          description: Error code
    DnaArticleUncaughtExceptionExample:
      type: object
      properties:
        title:
          type: string
          description: Error title
        id:
          type: string
          description: Article ID
        detail:
          type: string
          description: Detailed description of the error
        status:
          type: string
          description: Error status
          enum:
          - continue
          - switchingProtocols
          - oK
          - created
          - accepted
          - nonAuthoritativeInformation
          - noContent
          - resetContent
          - partialContent
          - multipleChoices
          - ambiguous
          - movedPermanently
          - moved
          - found
          - redirect
          - seeOther
          - redirectMethod
          - notModified
          - useProxy
          - unused
          - temporaryRedirect
          - redirectKeepVerb
          - badRequest
          - unauthorized
          - paymentRequired
          - forbidden
          - notFound
          - methodNotAllowed
          - notAcceptable
          - proxyAuthenticationRequired
          - requestTimeout
          - conflict
          - gone
          - lengthRequired
          - preconditionFailed
          - requestEntityTooLarge
          - requestUriTooLong
          - unsupportedMediaType
          - requestedRangeNotSatisfiable
          - expectationFailed
          - upgradeRequired
          - internalServerError
          - notImplemented
          - badGateway
          - serviceUnavailable
          - gatewayTimeout
          - httpVersionNotSupported
        code:
          type: string
          description: Error code
    DnaBulkArticleDrnIdRequest:
      type: object
      properties:
        refs:
          type: array
          items:
            type: string
    DnaArticleListExample:
      type: object
      properties:
        jsonapi:
          $ref: '#/components/schemas/JsonApiHeader'
        data:
          type: array
          description: Object with details about the requested resource
          items:
            $ref: '#/components/schemas/JsonApiResourceObject_DnaArticleData_'
        id:
          type: string
          description: A unique identifier for the requested resource
        links:
          type: object
          properties: {}
          description: Resource links
        meta:
          $ref: '#/components/schemas/ArticlesMeta'
    ArticlesMeta:
      type: object
      properties:
        metrics:
          $ref: '#/components/schemas/ArticlesMetric'
    ArticlesMetric:
      type: object
      properties:
        count:
          type: integer
          description: Number of records returned
          format: int32
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT