FINOS Streams API
The Streams API from FINOS — 16 operation(s) for streams.
OpenAPI Specification
openapi: 3.0.1
info:
title: Agent Admin Streams 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: Streams
paths:
/v1/im/create:
post:
summary: Create a new single or multi party instant message conversation between the caller and specified users.
description: 'At least one user ID must be provided or
an error response will be sent.
The caller is implicitly included in the members of the
created chat.
Duplicate users will be included in the membership of the chat but
the duplication will be silently ignored.
If there is an existing IM conversation with the same set of participants then
the id of that existing stream will be returned.
This method was incorrectly specified to take a query parameter in
version 1.0 of this specification but now expects a JSON array of
user IDs in the body of the request.
'
consumes:
- application/json
produces:
- application/json
parameters:
- name: uidList
description: List of (integer) User IDs of participants
in: body
required: true
schema:
$ref: '#/definitions/UserIdList'
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Streams
responses:
'200':
description: OK
schema:
$ref: '#/definitions/Stream'
examples:
application/json:
id: xhGxbTcvTDK6EIMMrwdOrX___quztr2HdA
'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/im/{id}/update:
post:
summary: Update the attributes of an existing IM.
consumes:
- application/json
produces:
- application/json
parameters:
- name: id
description: IM streamID
in: path
required: true
type: string
- name: payload
in: body
required: true
schema:
$ref: '#/definitions/V1IMAttributes'
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Streams
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V1IMDetail'
examples:
application/json:
V1IMAttributes:
pinnedMessageId: vd7qwNb6hLoUV0BfXXPC43___oPIvkwJbQ
IMSystemInfo:
id: usnBKBkH_BVrGOiVpaupEH___okFfE7QdA
creationDate: 1610520703317
active: true
'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
'451':
description: 'Unavailable for Legal Reasons: Compliance Issues found in IM update request.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 451
message: Compliance issues found in room update
'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/im/{id}/info:
get:
summary: Get information about a partcular IM.
produces:
- application/json
parameters:
- name: id
description: IM streamId
in: path
required: true
type: string
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Streams
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V1IMDetail'
examples:
application/json:
V1IMAttributes:
pinnedMessageId: vd7qwNb6hLoUV0BfXXPC43___oPIvkwJbQ
IMSystemInfo:
id: usnBKBkH_BVrGOiVpaupEH___okFfE7QdA
creationDate: 1610520703317
active: true
'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.
/v3/room/create:
post:
summary: Create a new chatroom.
description: 'Create a new chatroom.
If no attributes are specified, the room is created as a private chatroom.
'
consumes:
- application/json
produces:
- application/json
parameters:
- name: payload
in: body
required: true
schema:
$ref: '#/definitions/V3RoomAttributes'
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Streams
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V3RoomDetail'
examples:
application/json:
roomAttributes:
name: API room
keywords:
- key: region
value: EMEA
- key: lead
value: Bugs Bunny
description: Created via the API
membersCanInvite: true
discoverable: false
readOnly: false
copyProtected: false
crossPod: false
viewHistory: false
multiLateralRoom: false
public: false
groupChat: false
roomSystemInfo:
id: bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA
creationDate: 1547661232368
createdByUserId: 14362370637825
active: true
'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
'451':
description: 'Unavailable for Legal Reasons: Compliance Issues found in room creation request.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 451
message: Compliance issues found in room creation
'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.
/v3/room/search:
post:
summary: Search rooms according to the specified criteria.
produces:
- application/json
consumes:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: skip
description: 'No. of results to skip.
'
in: query
type: integer
- name: limit
description: 'Max no. of results to return. If no value is provided, 50 is the default. Must be a positive
integer and must not exceed 100
'
in: query
type: integer
required: false
- name: includeNonDiscoverable
description: Whether the non discoverable rooms should be returned. false by default. Parameter introduced in sbe-25.5.0
in: query
type: boolean
default: false
required: false
- name: query
description: The search query object.
in: body
required: true
schema:
$ref: '#/definitions/V2RoomSearchCriteria'
tags:
- Streams
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V3RoomSearchResults'
examples:
application/json:
count: 2
skip: 0
limit: 10
query:
query: automobile
labels:
- industry
active: true
creator:
id: 7696581411197
rooms:
- roomAttributes:
name: Automobile Industry Room
description: Room to discuss car companies
membersCanInvite: true
readOnly: false
copyProtected: false
crossPod: false
viewHistory: false
public: false
multiLateralRoom: false
roomSystemInfo:
id: tzwvAZIdDMG3ZPRxv+xsgH///qr+JJkWdA==
creationDate: 1464615003895
createdByUserId: 7696581411197
active: true
- roomAttributes:
name: Tesla Room
keywords:
- key: industry
value: automobile
description: Discussions on TSLA
membersCanInvite: true
readOnly: false
copyProtected: false
crossPod: false
viewHistory: false
public: false
multiLateralRoom: false
roomSystemInfo:
id: o6UkQ1TEmU0Tf/DHUlZrCH///qr+JQowdA==
creationDate: 1464614974947
createdByUserId: 7696581411197
active: true
facetedMatchCount:
- facet: industry
count: 1
'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.
/v3/room/{id}/info:
get:
summary: Get information about a partcular chatroom.
produces:
- application/json
parameters:
- name: id
description: Room streamId
in: path
required: true
type: string
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Streams
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V3RoomDetail'
examples:
application/json:
roomAttributes:
name: API room
keywords:
- key: region
value: EMEA
- key: lead
value: Bugs Bunny
description: Created via the API
membersCanInvite: true
discoverable: false
readOnly: false
copyProtected: false
crossPod: false
viewHistory: false
multiLateralRoom: false
public: false
groupChat: false
roomSystemInfo:
id: bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA
creationDate: 1547661232368
createdByUserId: 14362370637825
active: true
'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/room/{id}/setActive:
post:
summary: Deactivate or reactivate a chatroom. At creation, a new chatroom is active.
consumes:
- application/json
produces:
- application/json
parameters:
- name: id
description: Room streamId
in: path
required: true
type: string
- name: active
in: query
required: true
type: boolean
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Streams
responses:
'200':
description: OK
schema:
$ref: '#/definitions/RoomDetail'
examples:
application/json:
roomAttributes:
name: API room
description: Updated via the API
membersCanInvite: true
discoverable: true
roomSystemInfo:
id: HNmksPVAR6-f14WqKXmqHX___qu8LMLgdA
creationDate: 1461426797875
createdByUserId: 7078106103809
active: false
immutableRoomAttributes:
readOnly: false
copyProtected: false
public: false
'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.
/v3/room/{id}/update:
post:
summary: Update the attributes of an existing chatroom.
consumes:
- application/json
produces:
- application/json
parameters:
- name: id
description: Room streamId
in: path
required: true
type: string
- name: payload
in: body
required: true
schema:
$ref: '#/definitions/V3RoomAttributes'
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Streams
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V3RoomDetail'
examples:
application/json:
roomAttributes:
name: API room updated
keywords:
- key: region
value: EMEA
- key: lead
value: Bugs Bunny
description: Updated via the API
membersCanInvite: true
discoverable: false
readOnly: false
copyProtected: false
crossPod: false
viewHistory: true
multiLateralRoom: false
pinnedMessageId: vd7qwNb6hLoUV0BfXXPC43___oPIvkwJbQ
public: true
groupChat: false
roomSystemInfo:
id: bjHSiY4iz3ar4iIh6-VzCX___peoM7cPdA
creationDate: 1547661232368
createdByUserId: 14362370637825
active: true
'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
'451':
description: 'Unavailable for Legal Reasons: Compliance Issues found in room update request.'
schema:
$ref: '#/definitions/Error'
examples:
application/json:
code: 451
message: Compliance issues found in room update
'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/streams/list:
post:
summary: 'Retrieve a list of all streams of which the requesting user is a member,
sorted by creation date (ascending).
'
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: skip
description: 'No. of results to skip.
'
in: query
type: integer
- name: limit
description: 'Max no. of results to return. If no value is provided, 50 is the default.
'
in: query
type: integer
- name: filter
description: Stream filtering criteria.
in: body
schema:
$ref: '#/definitions/StreamFilter'
tags:
- Streams
responses:
'200':
description: OK
schema:
$ref: '#/definitions/StreamList'
examples:
application/json:
- id: iWyZBIOdQQzQj0tKOLRivX___qu6YeyZdA
crossPod: false
active: true
streamType:
type: POST
streamAttributes:
members:
- 7215545078229
'204':
description: Stream not found.
'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/user/{uid}/streams/list:
post:
summary: 'Retrieve a list of all streams of which this user is a member,
sorted by creation date (ascending). Since SBE 20.16.
'
consumes:
- application/json
produces:
- application/json
parameters:
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
- name: uid
description: 'User ID as a decimal integer
'
in: path
required: true
type: integer
format: int64
- name: skip
description: 'No. of results to skip.
'
in: query
type: integer
- name: limit
description: 'Max no. of results to return. If no value is provided, 50 is the default.
'
in: query
type: integer
- name: filter
description: Stream filtering criteria.
in: body
schema:
$ref: '#/definitions/StreamFilter'
tags:
- Streams
responses:
'200':
description: OK
schema:
$ref: '#/definitions/StreamList'
examples:
application/json:
- id: Jq6uPN4-uIop7lvjOkYdXX___nn9I0PHdA
crossPod: false
active: true
streamType:
type: IM
streamAttributes:
members:
- 9139690966401
- 9139691042211
- id: iWyZBIOdQQzQj0tKOLRivX___qu6YeyZdA
crossPod: false
active: true
streamType:
type: POST
streamAttributes:
members:
- 7215545078229
'204':
description: Stream not found.
'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/streams/{sid}/info:
get:
summary: Get information about a partcular stream.
produces:
- application/json
parameters:
- name: sid
description: Stream Id
in: path
required: true
type: string
- name: sessionToken
description: Session authentication token.
in: header
required: true
type: string
tags:
- Streams
responses:
'200':
description: OK
schema:
$ref: '#/definitions/V2StreamAttributes'
examples:
application/json:
id: BZQYepoT0Zf4vL_jpeMPqn___oEWvVy3dA
crossPod: false
origin: INTERNAL
active: true
lastMessageDate: 1644590972696
streamType:
type: ROOM
roomAttributes:
name: API room
groups:
- id: 68719476744
addedBy: 68719476743
'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/streams/{sid}/attachments:
get:
summary: Get attachments in a particular stream.
produces:
- application/json
parameters:
- name: sid
description: Stream Id
in: path
required: true
type: string
- name: since
description: 'Timestamp of first required attachment.
This is a long integer value representing milliseconds since Jan 1 1970
'
in: query
required: false
type: integer
format: int64
- name: to
description: 'Timestamp of last required attachment.
This is a long integer value representing milliseconds since Jan 1 1970
'
in: query
required: false
type: integer
format: int64
- name: limit
description: Maximum number of attachments to return. Default is 50. Must be a positive integer and must not exceed 100.
in: query
type: integer
required: false
- name: sortDir
description: 'Attachment date sort direction : ASC or DESC (default to ASC)
'
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/finos/refs/heads/main/openapi/finos-streams-api-openapi.yml