933 lines
24 KiB
YAML
933 lines
24 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
title: Corteza messaging API
|
|
description: Corteza messaging REST API definition
|
|
version: 2020.12
|
|
contact:
|
|
email: info@cortezaproject.org
|
|
license:
|
|
name: Apache 2.0
|
|
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
|
|
paths:
|
|
/commands/:
|
|
get:
|
|
tags:
|
|
- Commands
|
|
summary: List of available commands
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
/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
|
|
/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
|
|
/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
'/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
|
|
/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
|
|
/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
|
|
/permissions/:
|
|
get:
|
|
tags:
|
|
- Permissions
|
|
summary: Retrieve defined permissions
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
/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
|
|
'/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: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
roleID:
|
|
type: string
|
|
format: uuid
|
|
resource:
|
|
type: string
|
|
operation:
|
|
type: string
|
|
access:
|
|
type: string
|
|
description: List of permission rules to set
|
|
required:
|
|
- rules
|
|
application/x-www-form-urlencoded:
|
|
schema:
|
|
type: object
|
|
properties: *ref_16
|