openapi: 3.1.0
info:
  title: Reuters Connect Authentication Items API
  description: Reuters Connect Web Services is the professional content delivery platform providing REST API access to news, images, video, and data from Reuters and partner content sources. The API enables searching and retrieving editorial content with great specificity and speed, powering over 100 customer applications and internal systems. Content is organized into channels by category (text, images, video, graphics) and items can be retrieved individually or searched by keyword within channels.
  version: 1.0.0
  contact:
    name: Reuters API Support
    url: https://www.reutersconnect.com/contact
    email: api.support@thomsonreuters.com
  license:
    name: Reuters Terms of Use
    url: https://www.reuters.com/info-pages/terms-of-use/
  termsOfService: https://www.reuters.com/info-pages/terms-of-use/
servers:
- url: https://rmb.reuters.com/rmd/rest/xml
  description: Reuters Connect Content Delivery Server
- url: https://commerce.reuters.com/rmd/rest/xml
  description: Reuters Connect Authentication Server
security:
- tokenAuth: []
tags:
- name: Items
  description: Retrieve content items from specific channels. Items represent individual pieces of editorial content such as news stories, images, video clips, or graphics.
paths:
  /items:
    get:
      operationId: listItems
      summary: List Items on a Channel
      description: Retrieves a list of content items available on a specific channel. Returns the most recent items on the channel, including metadata such as headlines, timestamps, media types, and identifiers. Items can represent news stories, images, video clips, or graphics depending on the channel category.
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/token'
      - $ref: '#/components/parameters/channel'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/dateRange'
      - $ref: '#/components/parameters/mediaType'
      responses:
        '200':
          description: A list of items from the specified channel.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ItemListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /item:
    get:
      operationId: getItem
      summary: Retrieve a Specific Content Item
      description: Retrieves the full details of a specific content item by its unique identifier. The response includes the complete item metadata, content body, and available renditions (for media items). Items may be Simple News Items (SNI), News Event Packages (NEP), or Super News Event Packages (SNEP) for composite content.
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/token'
      - $ref: '#/components/parameters/itemId'
      responses:
        '200':
          description: The full details of the requested content item.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ItemResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Rendition:
      type: object
      description: A specific rendition or format of a media item. Renditions represent different sizes, resolutions, or formats of the same content available for download.
      properties:
        name:
          type: string
          description: The name or label of the rendition (e.g., thumbnail, preview, baseImage, videoFile).
        href:
          type: string
          format: uri
          description: The URL to download this rendition of the content.
        mimetype:
          type: string
          description: The MIME type of the rendition file (e.g., image/jpeg, video/mp4).
        width:
          type: integer
          description: The width of the rendition in pixels (for images and video).
        height:
          type: integer
          description: The height of the rendition in pixels (for images and video).
        sizeinbytes:
          type: integer
          description: The file size of the rendition in bytes.
      xml:
        name: rendition
    ItemListResponse:
      type: object
      description: Response containing a list of content items.
      properties:
        results:
          type: array
          description: Array of content item summaries.
          items:
            $ref: '#/components/schemas/ItemSummary'
        totalResults:
          type: integer
          description: Total number of items available on the channel.
      xml:
        name: results
    Association:
      type: object
      description: A reference to an associated content item, linking related pieces of editorial content together.
      properties:
        id:
          type: string
          description: The unique identifier of the associated item.
        type:
          type: string
          description: The type of association (e.g., companion, related, seeAlso).
        headline:
          type: string
          description: The headline of the associated item.
        mediaType:
          type: string
          description: The media type of the associated item.
      xml:
        name: association
    ItemSummary:
      type: object
      description: A summary representation of a content item, containing key metadata without the full content body.
      properties:
        id:
          type: string
          description: The unique identifier for the item, typically in URN or tag URI format.
        guid:
          type: string
          description: A globally unique identifier for the item regardless of version.
        version:
          type: string
          description: The version number of this item revision.
        headline:
          type: string
          description: The headline or title of the content item.
        dateCreated:
          type: string
          format: date-time
          description: The date and time when the item was originally created.
        dateModified:
          type: string
          format: date-time
          description: The date and time when the item was last modified.
        channel:
          type: string
          description: The alias of the channel this item belongs to.
        mediaType:
          type: string
          description: The media type of the content (TEXT, PICTURE, VIDEO, GRAPHIC).
          enum:
          - TEXT
          - PICTURE
          - VIDEO
          - GRAPHIC
          - COMPOSITE
        slug:
          type: string
          description: A short keyword slug summarizing the item topic.
      xml:
        name: item
    Subject:
      type: object
      description: A subject classification code from the IPTC NewsCodes taxonomy.
      properties:
        code:
          type: string
          description: The IPTC subject code.
        name:
          type: string
          description: The human-readable name of the subject category.
      xml:
        name: subject
    Error:
      type: object
      description: An error response from the Reuters Connect API.
      properties:
        code:
          type: string
          description: A machine-readable error code.
        message:
          type: string
          description: A human-readable error message describing the issue.
      xml:
        name: error
    ItemResponse:
      type: object
      description: Full details of a content item including metadata, content body, and available renditions.
      properties:
        id:
          type: string
          description: The unique identifier for the item.
        guid:
          type: string
          description: A globally unique identifier for the item.
        version:
          type: string
          description: The version number of this item revision.
        headline:
          type: string
          description: The headline or title of the content item.
        dateCreated:
          type: string
          format: date-time
          description: The date and time when the item was originally created.
        dateModified:
          type: string
          format: date-time
          description: The date and time when the item was last modified.
        channel:
          type: string
          description: The alias of the channel this item belongs to.
        slug:
          type: string
          description: A short keyword slug summarizing the item topic.
        mediaType:
          type: string
          description: The media type of the content.
          enum:
          - TEXT
          - PICTURE
          - VIDEO
          - GRAPHIC
          - COMPOSITE
        urgency:
          type: integer
          description: The editorial urgency priority of the item (1 = highest).
          minimum: 1
          maximum: 9
        byline:
          type: string
          description: The author or creator attribution for the item.
        dateline:
          type: string
          description: The location and date line for the item (e.g., NEW YORK, March 4).
        language:
          type: string
          description: The ISO 639-1 language code of the content.
        body:
          type: string
          description: The full text body of the content item. For text items, this contains the story body in XHTML. For media items, this may contain a caption or description.
        subjects:
          type: array
          description: Subject classification codes assigned to the item.
          items:
            $ref: '#/components/schemas/Subject'
        renditions:
          type: array
          description: Available renditions of the content. For images and video, this includes different sizes and formats available for download.
          items:
            $ref: '#/components/schemas/Rendition'
        associations:
          type: array
          description: Related items associated with this content, such as images accompanying a text story or stories related to an image.
          items:
            $ref: '#/components/schemas/Association'
      xml:
        name: item
  parameters:
    channel:
      name: channel
      in: query
      required: true
      description: The channel alias identifying which content channel to retrieve items from.
      schema:
        type: string
      examples:
        textChannel:
          value: OLDEN
          summary: A sample text news channel alias.
    mediaType:
      name: mediaType
      in: query
      required: false
      description: Filter results by media type to restrict to specific content formats.
      schema:
        type: string
        enum:
        - TEXT
        - PICTURE
        - VIDEO
        - GRAPHIC
        - COMPOSITE
    itemId:
      name: id
      in: query
      required: true
      description: The unique identifier of the content item to retrieve.
      schema:
        type: string
      examples:
        sampleId:
          value: tag:reuters.com,2025:newsml_L1N3KT0AB:1
          summary: A sample Reuters item identifier.
    token:
      name: token
      in: query
      required: true
      description: Authorization token obtained from the /login endpoint.
      schema:
        type: string
    dateRange:
      name: dateRange
      in: query
      required: false
      description: Filter results by date range. Specify a date range to restrict results to items published within that period.
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of items to return in the response.
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 25
  responses:
    Unauthorized:
      description: Authentication failed. The token is missing, expired, or invalid. Obtain a new token from the /login endpoint.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: An internal server error occurred. Try the request again later or contact Reuters API support.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found. The item ID or channel alias may be incorrect.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Access denied. Your subscription does not include access to the requested resource or channel.
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: query
      name: token
      description: Authorization token obtained from the /login endpoint. Must be included as a query parameter in all content API requests.