openapi: 3.0.0 info: title: Corteza messaging API description: Corteza messaging REST API definition version: 1.0.0 contact: email: contact@mail.com license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' paths: /messaging/commands/: get: tags: - Commands summary: List of available commands responses: '200': description: OK /messaging/status/: get: tags: - Status summary: See all current statuses responses: '200': description: OK post: tags: - Status summary: Set user's status responses: '200': description: OK requestBody: content: application/json: schema: type: object properties: &ref_0 icon: type: string description: Status icon message: type: string description: Status message expires: type: string description: >- Clear status when it expires (eg: when-active, afternoon, tomorrow 1h, 30m, 1 PM, 2019-05-20) application/x-www-form-urlencoded: schema: type: object properties: *ref_0 delete: tags: - Status summary: Clear status responses: '200': description: OK /messaging/activity/: post: tags: - User activity summary: >- Sends user's activity to all subscribers; globally or per channel/message. responses: '200': description: OK requestBody: content: application/json: schema: type: object properties: &ref_1 channelID: type: string description: >- Channel ID, if set, activity will be send only to subscribed users messageID: type: string description: 'Message ID, if set, channelID must be set as well' kind: type: string description: Arbitrary string required: - kind application/x-www-form-urlencoded: schema: type: object properties: *ref_1 /messaging/channels/: get: tags: - Channels summary: List channels responses: '200': description: OK parameters: - in: query name: query description: Search query required: false schema: &ref_2 type: string post: tags: - Channels summary: Create new channel responses: '200': description: OK requestBody: content: application/json: schema: type: object properties: &ref_3 name: type: string description: Name of Channel topic: type: string description: Subject of Channel type: type: string description: Channel type membershipPolicy: type: string description: 'Membership policy (eg: featured, forced)?' members: type: array items: *ref_2 description: Initial members of the channel application/x-www-form-urlencoded: schema: type: object properties: *ref_3 '/messaging/channels/{channelID}': put: tags: - Channels summary: Update channel details responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: &ref_5 type: string requestBody: content: application/json: schema: type: object properties: &ref_4 name: type: string description: Name of Channel topic: type: string description: Subject of Channel membershipPolicy: type: string description: 'Membership policy (eg: featured, forced)?' type: type: string description: Channel type organisationID: type: string description: Move channel to different organisation application/x-www-form-urlencoded: schema: type: object properties: *ref_4 get: tags: - Channels summary: Read channel details responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 '/messaging/channels/{channelID}/state': put: tags: - Channels summary: Update channel state responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 requestBody: content: application/json: schema: type: object properties: &ref_6 state: type: string description: 'Valid values: delete, undelete, archive, unarchive' required: - state application/x-www-form-urlencoded: schema: type: object properties: *ref_6 '/messaging/channels/{channelID}/flag': put: tags: - Channels summary: Update channel membership flag responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 requestBody: content: application/json: schema: type: object properties: &ref_7 flag: type: string description: 'Valid values: pinned, hidden, ignored' required: - flag application/x-www-form-urlencoded: schema: type: object properties: *ref_7 delete: tags: - Channels summary: Remove channel membership flag responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 '/messaging/channels/{channelID}/members': get: tags: - Channels summary: List channel members responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 '/messaging/channels/{channelID}/members/{userID}': put: tags: - Channels summary: Join channel responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: userID description: Member ID required: true schema: *ref_5 delete: tags: - Channels summary: Remove member from channel responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: userID description: Member ID required: true schema: *ref_5 '/messaging/channels/{channelID}/invite': post: tags: - Channels summary: Join channel responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 requestBody: content: application/json: schema: type: object properties: &ref_8 userID: type: array items: *ref_2 description: User ID application/x-www-form-urlencoded: schema: type: object properties: *ref_8 '/messaging/channels/{channelID}/attach': post: tags: - Channels summary: Attach file to channel responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 requestBody: content: application/json: schema: type: object properties: &ref_9 replyTo: type: string description: Upload as a reply upload: type: string format: binary description: File to upload required: - upload application/x-www-form-urlencoded: schema: type: object properties: *ref_9 '/messaging/channels/{channelID}/messages/': post: tags: - Messages summary: Post new message to the channel responses: '200': description: OK requestBody: content: application/json: schema: type: object properties: &ref_10 message: type: string description: Message contents (markdown) required: - message application/x-www-form-urlencoded: schema: type: object properties: *ref_10 parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 '/messaging/channels/{channelID}/messages/command/{command}/exec': post: tags: - Messages summary: Execute command responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: command description: Command to be executed required: true schema: *ref_2 requestBody: content: application/json: schema: type: object properties: &ref_11 input: type: string description: Arbitrary command input params: type: array items: *ref_2 description: Command parameters application/x-www-form-urlencoded: schema: type: object properties: *ref_11 '/messaging/channels/{channelID}/messages/mark-as-read': get: tags: - Messages summary: Manages read/unread messages in a channel or a thread responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: query name: threadID description: 'ID of thread (messageID) ' required: false schema: *ref_5 - in: query name: lastReadMessageID description: ID of the last read message required: false schema: *ref_5 '/messaging/channels/{channelID}/messages/{messageID}': put: tags: - Messages summary: Edit existing message responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: messageID description: Message ID required: true schema: *ref_5 requestBody: content: application/json: schema: type: object properties: &ref_12 message: type: string description: Message contents (markdown) required: - message application/x-www-form-urlencoded: schema: type: object properties: *ref_12 delete: tags: - Messages summary: Delete existing message responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: messageID description: Message ID required: true schema: *ref_5 '/messaging/channels/{channelID}/messages/{messageID}/replies': post: tags: - Messages summary: Reply to a message responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: messageID description: Message ID required: true schema: *ref_5 requestBody: content: application/json: schema: type: object properties: &ref_13 message: type: string description: Message contents (markdown) required: - message application/x-www-form-urlencoded: schema: type: object properties: *ref_13 '/messaging/channels/{channelID}/messages/{messageID}/pin': post: tags: - Messages summary: Pin message to channel (public bookmark) responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: messageID description: Message ID required: true schema: *ref_5 delete: tags: - Messages summary: Pin message to channel (public bookmark) responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: messageID description: Message ID required: true schema: *ref_5 '/messaging/channels/{channelID}/messages/{messageID}/bookmark': post: tags: - Messages summary: Bookmark a message (private bookmark) responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: messageID description: Message ID required: true schema: *ref_5 delete: tags: - Messages summary: Remove boomark from message (private bookmark) responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: messageID description: Message ID required: true schema: *ref_5 '/messaging/channels/{channelID}/messages/{messageID}/reaction/{reaction}': post: tags: - Messages summary: React to a message responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: messageID description: Message ID required: true schema: *ref_5 - in: path name: reaction description: Reaction required: true schema: *ref_2 delete: tags: - Messages summary: Delete reaction from a message responses: '200': description: OK parameters: - in: path name: channelID description: Channel ID required: true schema: *ref_5 - in: path name: messageID description: Message ID required: true schema: *ref_5 - in: path name: reaction description: Reaction required: true schema: *ref_2 '/messaging/attachment/{attachmentID}/original/{name}': get: tags: - Attachments summary: Serves attached file responses: '200': description: OK parameters: - in: path name: attachmentID description: Attachment ID required: true schema: *ref_5 - in: path name: name description: File name required: true schema: *ref_2 - in: query name: sign description: Signature required: true schema: *ref_2 - in: query name: userID description: User ID required: true schema: *ref_5 - in: query name: download description: Force file download required: false schema: &ref_14 type: boolean '/messaging/attachment/{attachmentID}/preview.{ext}': get: tags: - Attachments summary: Serves preview of an attached file responses: '200': description: OK parameters: - in: path name: attachmentID description: Attachment ID required: true schema: *ref_5 - in: path name: ext description: Preview extension/format required: true schema: *ref_2 - in: query name: sign description: Signature required: true schema: *ref_2 - in: query name: userID description: User ID required: true schema: *ref_5 /messaging/search/messages: get: tags: - Search entry point summary: Search for messages responses: '200': description: OK parameters: - in: query name: query description: Search query required: false schema: *ref_2 - in: query name: channelID description: Filter by channels required: false schema: type: array items: *ref_2 - in: query name: afterMessageID description: ID of the first message in the list (exclusive) required: false schema: *ref_5 - in: query name: beforeMessageID description: ID of the last message in the list (exclusive) required: false schema: *ref_5 - in: query name: fromMessageID description: ID of the first message in the list (inclusive) required: false schema: *ref_5 - in: query name: toMessageID description: ID of the last message the list (inclusive) required: false schema: *ref_5 - in: query name: threadID description: Filter by thread message ID required: false schema: type: array items: *ref_2 - in: query name: userID description: Filter by one or more user required: false schema: type: array items: *ref_2 - in: query name: type description: 'Filter by message type (text, inlineImage, attachment, ...)' required: false schema: type: array items: *ref_2 - in: query name: pinnedOnly description: Return only pinned messages required: false schema: *ref_14 - in: query name: bookmarkedOnly description: Only bookmarked messages required: false schema: *ref_14 - in: query name: limit description: Max number of messages required: false schema: &ref_15 type: string /messaging/search/threads: get: tags: - Search entry point summary: Search for threads responses: '200': description: OK parameters: - in: query name: query description: Search query required: false schema: *ref_2 - in: query name: channelID description: Filter by channels required: false schema: type: array items: *ref_2 - in: query name: limit description: Max number of messages required: false schema: *ref_15 /messaging/permissions/: get: tags: - Permissions summary: Retrieve defined permissions responses: '200': description: OK /messaging/permissions/effective: get: tags: - Permissions summary: Effective rules for current user responses: '200': description: OK parameters: - in: query name: resource description: Show only rules for a specific resource required: false schema: *ref_2 '/messaging/permissions/{roleID}/rules': get: tags: - Permissions summary: Retrieve role permissions responses: '200': description: OK parameters: - in: path name: roleID description: Role ID required: true schema: *ref_5 delete: tags: - Permissions summary: Remove all defined role permissions responses: '200': description: OK parameters: - in: path name: roleID description: Role ID required: true schema: *ref_5 patch: tags: - Permissions summary: Update permission settings responses: '200': description: OK parameters: - in: path name: roleID description: Role ID required: true schema: *ref_5 requestBody: content: application/json: schema: type: object properties: &ref_16 rules: type: string description: List of permission rules to set required: - rules application/x-www-form-urlencoded: schema: type: object properties: *ref_16