# Organisations Organisations represent a top-level grouping entity. There may be many organisations defined in a single deployment. ## List organisations #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | query | string | GET | Search query | N/A | NO | ## Create organisation #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | name | string | POST | Organisation Name | N/A | YES | ## Update organisation details #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/{id}` | HTTP/S | PUT | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | id | uint64 | PATH | Organisation ID | N/A | NO | | name | string | POST | Organisation Name | N/A | YES | ## Remove organisation #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/{id}` | HTTP/S | DELETE | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | id | uint64 | PATH | Organisation ID | N/A | YES | ## Read organisation details #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/{id}` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | id | uint64 | GET | Organisation ID | N/A | YES | ## Archive organisation #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/organisations/{id}/archive` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | id | uint64 | PATH | Organisation ID | N/A | YES | # Teams An organisation may have many teams. Teams may have many channels available. Access to channels may be shared between teams. ## List teams #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/teams/` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | query | string | GET | Search query | N/A | NO | ## Update team details #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/teams/` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | name | string | POST | Name of Team | N/A | YES | | members | []uint64 | POST | Team member IDs | N/A | NO | ## Update team details #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/teams/{teamID}` | HTTP/S | PUT | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | teamID | uint64 | PATH | Team ID | N/A | YES | | name | string | POST | Name of Team | N/A | NO | | members | []uint64 | POST | Team member IDs | N/A | NO | ## Read team details and memberships #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/teams/{teamID}` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | teamID | uint64 | PATH | Team ID | N/A | YES | ## Remove team #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/teams/{teamID}` | HTTP/S | DELETE | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | teamID | uint64 | PATH | Team ID | N/A | YES | ## Archive team #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/teams/{teamID}/archive` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | teamID | uint64 | PATH | Team ID | N/A | YES | ## Move team to different organisation #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/teams/{teamID}/move` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | teamID | uint64 | PATH | Team ID | N/A | YES | | organisation_id | uint64 | POST | Team ID | N/A | YES | ## Merge one team into another #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/teams/{teamID}/merge` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | teamID | uint64 | PATH | Source Team ID | N/A | YES | | destination | uint64 | POST | Destination Team ID | N/A | YES | # Channels A channel is a representation of a sequence of messages. It has meta data like channel subject. Channels may be public, private or direct (between two users). ## List channels #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | query | string | GET | Search query | N/A | NO | ## Create new channel #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | name | string | POST | Name of Channel | N/A | YES | | topic | string | POST | Subject of Channel | N/A | NO | ## Update channel details #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}` | HTTP/S | PUT | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | channelID | uint64 | PATH | Channel ID | N/A | YES | | name | string | POST | Name of Channel | N/A | NO | | topic | string | POST | Subject of Channel | N/A | NO | | archive | bool | POST | Request channel to be archived or unarchived | N/A | NO | | organisationID | uint64 | POST | Move channel to different organisation | N/A | NO | ## Read channel details #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | channelID | uint64 | PATH | Channel ID | N/A | YES | ## Remove channel #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}` | HTTP/S | DELETE | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | channelID | uint64 | PATH | Channel ID | N/A | YES | ## Join channel #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}/members` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | channelID | uint64 | PATH | Channel ID | N/A | YES | ## Join channel #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}/members/{userID}` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | channelID | uint64 | PATH | Channel ID | N/A | YES | ## Remove member from channel #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}/members/{userID}` | HTTP/S | DELETE | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | channelID | uint64 | PATH | Channel ID | N/A | YES | | userID | uint64 | PATH | Member ID | N/A | YES | ## Join channel #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}/invite` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | channelID | uint64 | PATH | Channel ID | N/A | YES | | userID | []uint64 | POST | User ID | N/A | NO | # Messages Messages represent individual messages in the chat system. Messages are typed, indicating the event which triggered the message. Currently expected message types are: | Name | Description | | ---- | ----------- | | CREATE | The first message when the channel is created | | TOPIC | A member changed the topic of the channel | | RENAME | A member renamed the channel | | MESSAGE | A member posted a message to the channel | | FILE | A member uploaded a file to the channel | The following event types may be sent with a message event: | Name | Description | | ---- | ----------- | | CREATED | A message has been created on a channel | | EDITED | A message has been edited by the sender | | REMOVED | A message has been removed by the sender | ## Post new message to the channel #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}/messages/` | HTTP/S | POST | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | message | string | POST | Message contents (markdown) | N/A | YES | ## All messages (channel history) #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}/messages/` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | lastMessageID | uint64 | GET | | N/A | NO | ## Edit existing message #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}/messages/{messageID}` | HTTP/S | PUT | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | messageID | uint64 | PATH | Message ID | N/A | YES | | message | string | POST | Message contents (markdown) | N/A | YES | ## Delete existing message #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}/messages/{messageID}` | HTTP/S | DELETE | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | messageID | uint64 | PATH | Message ID | N/A | YES | ## Attach file to message #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}/messages/{messageID}/attach` | HTTP/S | PUT | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | ## Search messages #### Method | URI | Protocol | Method | Authentication | | --- | -------- | ------ | -------------- | | `/channels/{channelID}/messages/search` | HTTP/S | GET | Client ID, Session ID | #### Request parameters | Parameter | Type | Method | Description | Default | Required? | | --------- | ---- | ------ | ----------- | ------- | --------- | | query | string | GET | Search string to match against messages | N/A | NO | | message_type | string | GET | Limit results to message type | N/A

Values: