FINOS Admin API

openapi: 3.0.1
info:
  title: Agent Admin API
  description: 'This document refers to Symphony API calls to send and receive messages

    and content. They need the on-premise Agent installed to perform

    decryption/encryption of content.


    - sessionToken and keyManagerToken can be obtained by calling the

    authenticationAPI on the symphony back end and the key manager

    respectively. Refer to the methods described in authenticatorAPI.yaml.

    - Actions are defined to be atomic, ie will succeed in their entirety

    or fail and have changed nothing.

    - If it returns a 40X status then it will have sent no message to any

    stream even if a request to some subset of the requested streams

    would have succeeded.

    - If this contract cannot be met for any reason then this is an error

    and the response code will be 50X.

    - MessageML is a markup language for messages. See reference here:

    https://rest-api.symphony.com/docs/messagemlv2

    - **Real Time Events**: The following events are returned when reading

    from a real time messages and events stream ("datafeed"). These

    events will be returned for datafeeds created with the v5 endpoints.

    To know more about the endpoints, refer to Create Messages/Events

    Stream and Read Messages/Events Stream. Unless otherwise specified,

    all events were added in 1.46.

    '
  version: 25.8.1
servers:
- url: youragentURL.symphony.com/agent
tags:
- name: Admin
paths:
  /v1/admin/messages:
    post:
      summary: Fetch message details
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: sessionToken
        description: Session authentication token
        in: header
        required: true
        type: string
      - name: messageIds
        description: the ids of the messages to be fetched
        in: body
        required: true
        schema:
          $ref: '#/definitions/MessageIds'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/MessageDetails'
        '400':
          description: Client error, see response body for further details.
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 400
              message: // Client error, see response body for further details.
        '401':
          description: 'Unauthorized: Invalid session token.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 401
              message: Invalid session
        '403':
          description: 'Forbidden: Caller lacks necessary entitlement.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 403
              message: The user lacks the required entitlement to perform this operation
        '404':
          description: 'Not Found: Message ID could not be found.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 403
              message: // Not Found. Message ID could not be found. See response body for fruther details.
        '422':
          description: 'Unprocessable entity: Invalid message type.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 422
              message: // Unprocessable Entity. Invalid message type. See response body for further details.
        '500':
          description: Server error, see response body for further details.
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 500
              message: // Server error, see response body for further details.
      tags:
      - Admin
  /v1/admin/messages/{messageId}/receipts:
    get:
      summary: Fetch receipts details from a specific message.
      produces:
      - application/json
      parameters:
      - name: sessionToken
        description: Session authentication token.
        in: header
        required: true
        type: string
      - name: messageId
        description: The message ID
        in: path
        required: true
        type: string
      - name: before
        description: Returns results from an opaque “before” cursor value as presented via a response cursor.
        in: query
        required: false
        type: string
      - name: after
        description: Returns results from an opaque “after” cursor value as presented via a response cursor.
        in: query
        required: false
        type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/MessageReceiptDetailResponse'
          examples:
            application/json:
              creator:
                id: 7215545058329
                name: User Test
              stream:
                id: lFpyw0ATFmji+Cc/cSzbk3///pZkWpe1dA==
                name: Test Room
                streamType: ROOM
              creationDate: 1552999333141
              deliveryReceiptCount: 1
              readReceiptCount: 1
              emailNotificationCount: 1
              downloadReceiptCounts:
              - fileName: internal_7078106
                count: 1
              MessageReceiptDetail:
              - user:
                  id: 7215545058313
                  username: dpayet
                  firstName: Dimitiri
                  lastName: Payet
                  emailAddress: dpayet@om.fr
                deliveryReceiptTimestamp: 1552999333784
                readReceiptTimestamp: 1552999335114
                emailNotificationTimestamp: 1552999335114
                downloadReceiptCounts:
                - fileName: Untitled Document.txt
                  timestamp: 1552999335740
        '400':
          description: Client error, see response body for further details.
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 400
              message: // Client error, see response body for further details.
        '401':
          description: 'Unauthorized: Invalid session token.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 401
              message: Invalid session
        '403':
          description: 'Forbidden: Caller lacks necessary entitlement.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 403
              message: The user lacks the required entitlement to perform this operation
        '404':
          description: 'Not Found: Message receipt details cannot be found.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 403
              message: // Not Found. Message receipt details cannot be found. See response body for fruther details.
        '500':
          description: Server error, see response body for further details.
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 500
              message: // Server error, see response body for further details.
      tags:
      - Admin
  /v1/admin/messages/{messageId}/metadata/relationships:
    get:
      summary: Get the message metadata relationship
      produces:
      - application/json
      parameters:
      - name: sessionToken
        description: Session authentication token.
        in: header
        required: true
        type: string
      - name: User-Agent
        description: Request user agent.
        in: header
        required: true
        type: string
      - name: messageId
        in: path
        description: Valid id of a SOCIALMESSAGE
        required: true
        type: string
      responses:
        '200':
          description: Successful Operation
          schema:
            $ref: '#/definitions/MessageMetadataResponse'
        '400':
          description: Client error, see response body for further details.
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 400
              message: // Client error, see response body for further details.
        '401':
          description: 'Unauthorized: Invalid session token.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 401
              message: Invalid session
        '403':
          description: 'Forbidden: Caller lacks necessary entitlement.'
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 403
              message: The user lacks the required entitlement to perform this operation
        '500':
          description: Server error, see response body for further details.
          schema:
            $ref: '#/definitions/Error'
          examples:
            application/json:
              code: 500
              message: // Server error, see response body for further details.
      tags:
      - Admin
definitions:
  MessageUser:
    type: object
    properties:
      id:
        type: integer
        format: int64
        example: 7215545058329
      name:
        type: string
        example: User Test
  MessageStream:
    type: object
    properties:
      id:
        type: string
        example: lFpyw0ATFmji+Cc/cSzbk3///pZkWpe1dA==
      name:
        type: string
        example: Test Room
      streamType:
        type: string
        example: ROOM
  MessageDetail:
    description: Message detail
    type: object
    properties:
      messageId:
        description: message id
        type: string
      creator:
        $ref: '#/definitions/MessageUser'
      onBehalfOfUser:
        $ref: '#/definitions/MessageUser'
      stream:
        $ref: '#/definitions/MessageStream'
      creationDate:
        type: integer
        format: int64
      deliveryReceiptCount:
        type: integer
        format: int64
      readReceiptCount:
        type: integer
        format: int64
      emailNotificationCount:
        type: integer
        format: int64
      downloadReceiptCounts:
        type: array
        items:
          $ref: '#/definitions/MessageDownloadReceiptCount'
  MessageDownloadReceiptCount:
    type: object
    properties:
      fileName:
        type: string
        example: internal_707810
      count:
        type: integer
        format: int64
        example: 1
  DownloadReceiptCount:
    type: object
    properties:
      fileName:
        type: string
        example: Untitled Document.txt
      timestamp:
        type: integer
        format: int64
        example: 1552999335740
  MessageDetails:
    description: Message details
    type: array
    items:
      $ref: '#/definitions/MessageDetail'
  MessageReceiptDetail:
    description: Message receipt details response object
    type: object
    properties:
      user:
        $ref: '#/definitions/UserCompp'
      deliveryReceiptTimestamp:
        description: Timestamp of message delivery receipts
        type: integer
        format: int64
        example: 1552999333784
      readReceiptTimestamp:
        description: Timestamp of message read receipts
        type: integer
        format: int64
        example: 1552999335114
      emailNotificationTimestamp:
        description: Timestamp of message email notifications
        type: integer
        format: int64
        example: 1552999335114
      downloadReceiptCounts:
        type: array
        items:
          $ref: '#/definitions/DownloadReceiptCount'
        example:
        - fileName: Untitled Document.txt
          timestamp: 1552999335740
  MessageReceiptDetailResponse:
    description: List of Message receipt details
    type: object
    properties:
      creator:
        $ref: '#/definitions/MessageUser'
      onBehalfOfUser:
        $ref: '#/definitions/MessageUser'
      stream:
        $ref: '#/definitions/MessageStream'
      creationDate:
        type: integer
        format: int64
        example: 1552999333141
      deliveryReceiptCount:
        type: integer
        example: 1
      readReceiptCount:
        type: integer
        example: 1
      emailNotificationCount:
        type: integer
        example: 1
      downloadReceiptCounts:
        type: array
        items:
          $ref: '#/definitions/MessageDownloadReceiptCount'
        example:
        - fileName: internal_70781
          count: 1
      MessageReceiptDetail:
        type: array
        items:
          $ref: '#/definitions/MessageReceiptDetail'
        example:
        - user:
            id: 7215545058329
            username: dpayet
            firstName: Dimitri
            lastName: Payet
            emailAddress: dpayet@om.fr
          deliveryReceiptTimestamp: 1552999333784
          readReceiptTimestamp: 1552999335114
          emailNotificationTimestamp: 1552999335114
          downloadReceiptCounts:
          - fileName: Untitled Document.txt
            timestamp: 1552999335740
      pagination:
        $ref: '#/definitions/Pagination'
  StringList:
    type: array
    items:
      type: string
    example:
    - ftp
    - mailto
    - fdsup
    - skype
  UserCompp:
    description: Basic user information to include in other models
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: User ID
        example: 7215545058329
      username:
        type: string
        description: Username
        example: dpayet
      firstName:
        type: string
        description: User first name
        example: Dimitri
      lastName:
        type: string
        description: User last name
        example: Payet
      emailAddress:
        type: string
        description: User email addressIntegrationUserManagerTest
        example: dpayet@om.fr
  Pagination:
    type: object
    required:
    - cursors
    properties:
      cursors:
        type: object
        required:
        - before
        properties:
          before:
            type: string
            description: 'This is the opaque url-safe string that points to the start of the page of data

              that has been returned.

              '
            example: MTAxNTExOTQ1MjAwNzI5NDE=
          after:
            type: string
            description: 'This is the opaque url-safe string that points to the end of the page of data

              that has been returned.

              '
            example: NDMyNzQyODI3OTQw
      previous:
        type: string
        description: 'API endpoint that will return the previous page of data. If not included, this is

          the first page of data.

          '
        example: https://tenantapi.d.isym.io/v1/tenantinfo?limit=25&before=MTAxNTExOTQ1MjAwNzI5NDE=
      next:
        type: string
        description: 'API endpoint that will return the next page of data. If not included, this is the

          last page of data. Due to how pagination works with visibility and privacy, it is

          possible that a page may be empty but contain a ''next'' paging link. Stop paging when

          the ''next'' link no longer appears.

          '
        example: https://tenantapi.d.isym.io/v1/tenantinfo?limit=25&after=NDMyNzQyODI3OTQw
  MessageIds:
    type: object
    properties:
      messageIds:
        $ref: '#/definitions/StringList'
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
        example: 401
      message:
        type: string
        example: Invalid session
  MessageMetadataResponse:
    description: Message metadata
    type: object
    properties:
      messageId:
        type: string
      parent:
        type: object
        properties:
          messageId:
            type: string
            description: Id of the parent message queried
          relationshipType:
            type: string
            enum:
            - REPLY_FORM
            - REPLY
            - FORWARD
      replies:
        type: array
        items:
          type: string
      forwards:
        type: array
        items:
          type: string
      formReplies:
        type: array
        items:
          type: string