FINOS System API

openapi: 3.0.1
info:
  title: Agent Admin System 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: System
paths:
  /v3/health:
    get:
      tags:
      - System
      summary: Checks health status
      description: '_Available on Agent 2.57.0 and above._


        Returns the connectivity status of your Agent server. If your Agent server is started and running, the status value will be `UP`

        '
      operationId: v3Health
      responses:
        200:
          description: Agent application is alive.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3Health'
              example:
                status: UP
  /v3/health/extended:
    get:
      tags:
      - System
      summary: Checks health status of services and users
      description: '_Available on Agent 2.57.0 and above._


        Returns the connectivity status of the Agent services (**pod**, **key manager** and **datafeed**) as well as users

        connectivity (**agentservice** and **ceservice**).


        The global status will be set to `DOWN` if at least one of the sub-status is also `DOWN`.

        '
      operationId: v3ExtendedHealth
      responses:
        200:
          description: Agent is healthy, all components are `UP`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3Health'
              example:
                services:
                  pod:
                    status: UP
                    version: 24.1.1-411-36efd5b
                  key_manager:
                    status: UP
                    version: 24.1.1-411-36efd5b
                  datafeed:
                    status: UP
                    version: 2.11.6
                status: UP
                users:
                  agentservice:
                    authType: RSA
                    status: UP
                  ceservice:
                    authType: RSA
                    status: UP
                version: 24.3.2-778
        503:
          description: Agent is unhealthy, some components are `DOWN`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3Health'
              example:
                services:
                  pod:
                    status: UP
                    version: 24.1.1-411-36efd5b
                  key_manager:
                    status: DOWN
                    version: 24.1.1-411-36efd5b
                  datafeed:
                    status: UP
                    version: 2.11.6
                status: UP
                users:
                  agentservice:
                    authType: RSA
                    status: UP
                  ceservice:
                    authType: RSA
                    status: UP
                version: 24.3.2-778
  /v1/admin/system/features/list:
    get:
      summary: Get the full set of Symphony features available for this pod
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: sessionToken
        description: Session authentication token.
        in: header
        required: true
        type: string
      tags:
      - System
      responses:
        '200':
          description: The list of valid feature entitlement names.
          schema:
            $ref: '#/definitions/StringList'
          examples:
            application/json:
            - postReadEnabled
            - canCreatePublicRoom
            - canJoinMultiLateralRoom
        '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.
  /v1/admin/system/protocols/list:
    get:
      summary: Get a list of all URI protocols supported by the company (pod)
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: sessionToken
        description: Session authentication token.
        in: header
        required: true
        type: string
      tags:
      - System
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/StringList'
        '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.
  /v2/system/protocols:
    get:
      summary: Get a list of URI protocols supported by the company (pod)
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: sessionToken
        description: Session authentication token.
        in: header
        required: true
        type: string
      - name: skip
        description: Number of items to skip. Default is 0.
        in: query
        type: integer
        required: false
      - name: limit
        description: Maximum number of items to return. Default is 100 and not to exceed 1000.
        in: query
        type: integer
        required: false
      tags:
      - System
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/StringList'
          examples:
            application/json:
            - ftp
            - mailto
            - skype
        '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.
  /v1/admin/system/protocols:
    post:
      summary: Add an entry to URI protocols supported by the company (pod)
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: sessionToken
        description: Session authentication token.
        in: header
        required: true
        type: string
      - name: protocol
        required: true
        description: the protocol to add
        in: body
        schema:
          $ref: '#/definitions/Protocol'
      tags:
      - System
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Protocol'
          examples:
            application/json:
              scheme: skype
        '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.
  /v1/admin/system/protocols/{scheme}:
    delete:
      summary: Remove an entry from URI protocols supported by the company (pod)
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: sessionToken
        description: Session authentication token.
        in: header
        required: true
        type: string
      - name: scheme
        required: true
        description: the scheme to remove from the protocols list
        in: path
        type: string
      tags:
      - System
      responses:
        '204':
          description: 204 response
        '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.
components:
  schemas:
    V3HealthComponent:
      type: object
      properties:
        authType:
          $ref: '#/components/schemas/V3HealthAuthType'
        message:
          type: string
          description: An error message, if the component status is DOWN
        status:
          $ref: '#/components/schemas/V3HealthStatus'
        version:
          type: string
          description: Optional component version
    V3Health:
      type: object
      properties:
        services:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/V3HealthComponent'
        status:
          $ref: '#/components/schemas/V3HealthStatus'
        users:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/V3HealthComponent'
        version:
          type: string
          description: Required Agent verison
    V3HealthAuthType:
      type: string
      description: Type of authentication
      enum:
      - RSA
      - CERT
    V3HealthStatus:
      type: string
      description: Application health status.
      enum:
      - UP
      - DOWN
definitions:
  StringList:
    type: array
    items:
      type: string
    example:
    - ftp
    - mailto
    - fdsup
    - skype
  Protocol:
    type: object
    required:
    - scheme
    properties:
      scheme:
        type: string
        description: 'URI protocol scheme (example: http, https, ftp)'
        example: skype
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
        example: 401
      message:
        type: string
        example: Invalid session