openapi: 3.0.1
info:
  title: Symphony Agent Add Search 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: 22.9.1
servers:
- url: /
tags:
- name: Search
paths:
  /v1/message/search:
    get:
      tags:
      - Search
      summary: Search Messages
      description: "Search messages according to the specified criteria. The \"query\" parameter takes a search query defined as\n\"field:value\" pairs combined by the operator \"AND\" (e.g. \"text:foo AND autor:bar\"). Supported fields are\n (case-insensitive): \"text\", \"author\", \"hashtag\", \"cashtag\", \"mention\", \"signal\", \"fromDate\", \"toDate\",\n \"streamId\", \"streamType\".\n \"text\" search requires a \"streamId\" to be specified.\n \"streamType\" accepts one of the following values: \"chat\" (IMs and MIMs), \"im\", \"mim\", \"chatroom\", \"post\".\n \"signal\" queries can only be combined with \"fromDate\", \"toDate\", \"skip\" and \"limit\" parameters.\n"
      parameters:
      - name: query
        in: query
        description: The search query. See above for the query syntax.
        required: true
        schema:
          type: string
      - name: skip
        in: query
        description: No. of results to skip.
        schema:
          type: integer
      - name: limit
        in: query
        description: Max no. of results to return. If no value is provided, 50 is the default.
        schema:
          type: integer
      - name: scope
        in: query
        description: 'Describes where content should be searched for that query.

          It can exclusively apply to Symphony content or to one Connector.

          '
        schema:
          type: string
      - name: sortDir
        in: query
        description: 'Messages sort direction : ASC or DESC (default to DESC)

          '
        schema:
          type: string
      - name: sessionToken
        in: header
        description: Session authentication token.
        required: true
        schema:
          type: string
      - name: keyManagerToken
        in: header
        description: Key Manager authentication token.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4MessageList'
        '204':
          description: No Messages.
          content: {}
        '400':
          description: Client error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '401':
          description: 'Unauthorized: Session tokens invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '403':
          description: 'Forbidden: Caller lacks necessary entitlement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '500':
          description: Server error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
    post:
      tags:
      - Search
      summary: Search Messages
      description: Search messages according to the specified criteria.
      parameters:
      - name: skip
        in: query
        description: No. of results to skip.
        schema:
          type: integer
      - name: limit
        in: query
        description: Max no. of results to return. If no value is provided, 50 is the default.
        schema:
          type: integer
      - name: scope
        in: query
        description: 'Describes where content should be searched for that query.

          It can exclusively apply to Symphony content or to one Connector.

          '
        schema:
          type: string
      - name: sortDir
        in: query
        description: 'Messages sort direction : ASC or DESC (default to DESC)

          '
        schema:
          type: string
      - name: sessionToken
        in: header
        description: Session authentication token.
        required: true
        schema:
          type: string
      - name: keyManagerToken
        in: header
        description: Key Manager authentication token.
        required: true
        schema:
          type: string
      requestBody:
        description: The search query. See above for the query syntax.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageSearchQuery'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4MessageList'
        '204':
          description: No Messages.
          content: {}
        '400':
          description: Client error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '401':
          description: 'Unauthorized: Session tokens invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '403':
          description: 'Forbidden: Caller lacks necessary entitlement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '500':
          description: Server error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
      x-codegen-request-body-name: query
components:
  schemas:
    V4AttachmentInfo:
      required:
      - id
      - name
      - size
      - images
      type: object
      properties:
        id:
          type: string
          description: The attachment ID.
        name:
          type: string
          description: The file name.
        size:
          type: integer
          description: Size in bytes.
          format: int64
        images:
          type: array
          items:
            $ref: '#/components/schemas/V4ThumbnailInfo'
    V4Message:
      type: object
      properties:
        messageId:
          type: string
          description: Id of the message
        parentMessageId:
          type: string
          description: Id of the parent message, set when the message is a reply to another message or a forwarded message. Since Agent 20.14.
          x-since: 20.14
        timestamp:
          type: integer
          description: Timestamp of the message in milliseconds since Jan 1 1970
          format: int64
        message:
          type: string
          description: Message content in MessageMLV2
          format: MessageMLV2
        sharedMessage:
          $ref: '#/components/schemas/V4Message'
        data:
          type: string
          description: Message data in EntityJSON
          format: JSON
        attachments:
          type: array
          default: []
          description: Message attachments
          items:
            $ref: '#/components/schemas/V4AttachmentInfo'
        user:
          $ref: '#/components/schemas/V4User'
        stream:
          $ref: '#/components/schemas/V4Stream'
        externalRecipients:
          type: boolean
          description: Indicates if the message have external recipients. Only present on real time messaging.
        diagnostic:
          type: string
          description: 'Details if event failed to parse for any reason.  The contents of this field may not be useful,

            depending on the nature of the error. Only present when error occurs.

            '
        userAgent:
          type: string
          description: 'User agent string for client that sent the message.  Allows callers to identify which client sent the

            origin message (e.g. API Agent, SFE Client, mobile, etc)

            '
        originalFormat:
          type: string
          description: 'Indicates the format in which the message was originally sent.  This could have been either:

            - com.symphony.markdown - Markdown OR Message ML V1

            - com.symphony.messageml.v2 - Message ML V2

            '
        disclaimer:
          type: string
          description: 'Message that may be sent along with a regular message if configured for the POD,

            usually the first message sent in a room that day.

            '
        sid:
          type: string
          description: 'Unique session identifier from where the message was created.

            '
          example: fa691cd3-484a-4109-aeb2-57c05b78c95b
        replacing:
          type: string
          description: Id of the message that the current message is replacing (present only if set)
        replacedBy:
          type: string
          description: Id of the message that the current message is being replaced with (present only if set)
        initialTimestamp:
          type: integer
          description: "Timestamp of when the initial message has been created in milliseconds since \nJan 1 1970 (present only if set)\n"
          format: int64
        initialMessageId:
          type: string
          description: Id the the initial message that has been updated (present only if set)
        silent:
          type: boolean
          description: When false the user/s will receive the message update as unread (true by default)
          x-since: 20.14
      description: A representation of a message sent by a user of Symphony
    V4ThumbnailInfo:
      type: object
      properties:
        id:
          type: string
          description: The thumbnail ID.
        dimension:
          type: string
          description: The thumbnail pixel size.
    V4MessageList:
      type: array
      items:
        $ref: '#/components/schemas/V4Message'
    V2Error:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: object
    V4Stream:
      type: object
      properties:
        streamId:
          type: string
          description: Id of stream
        streamType:
          type: string
          description: "Stream type, possible values are:\n  - IM\n  - MIM\n  - ROOM\n  - POST\n"
        roomName:
          type: string
          description: Applicable only to rooms
        members:
          type: array
          description: Applicable only to IM Created
          items:
            $ref: '#/components/schemas/V4User'
        external:
          type: boolean
        crossPod:
          type: boolean
        recipientTenantIds:
          type: array
          description: 'List of tenant identifiers (aka pod identifiers) involved in the conversation. It contains more than one

            item if the conversation is external. Field is only present for real time messaging.

            '
          items:
            type: integer
            format: int32
          x-since: 24.2
    MessageSearchQuery:
      type: object
      properties:
        text:
          type: string
          description: Search for messages containing this text. Requires streamId to be specified.
        streamId:
          type: string
          description: Search for messages sent to this stream
        streamType:
          type: string
          description: 'Search for messages sent to this type of streams. Accepted values are CHAT, IM, MIM, ROOM, POST.

            '
        author:
          type: integer
          description: Search for messages sent by this user ID
          format: int64
        hashtag:
          type: string
          description: Search for messages containing this hashtag
        cashtag:
          type: string
          description: Search for messages containing this cashtag
        mention:
          type: integer
          description: Search for messages mentioning this user ID
          format: int64
        signal:
          type: string
          description: 'Search for messages matching this signal. Can only be combined with date filtering and paging parameters.

            '
        fromDate:
          type: integer
          description: Search for messages sent on or after this timestamp
          format: int64
        toDate:
          type: integer
          description: Search for messages sent before this timestamp
          format: int64
    V4User:
      type: object
      properties:
        userId:
          type: integer
          description: Id of user
          format: int64
        firstName:
          type: string
          description: First name of user
        lastName:
          type: string
          description: Last name of user
        displayName:
          type: string
          description: User display name
        email:
          type: string
          description: Email of user
        username:
          type: string
          description: Applicable only to internal users