pimentaCHAT REST API
The REST API allows you to control and extend pimentaCHAT with ease.
This API is a work in progress, so feel free to test, ask us questions, and submit Pull Requests!
If you are an end-user and not a dev or a tester, create a New Feature Request to request new APIs.
All API calls in the documentation are made using curl. However, you are free to use Java / Python / PHP / Golang / Ruby / Swift / Objective-C / Rust / Scala / C# or any other programming languages.
Production Security Concerns
When calling a production pimentaCHAT server, ensure it is running via HTTPS and has a valid SSL Certificate. The login method requires you to post your username and password in plaintext, which is why we highly suggest only calling the REST login API over HTTPS. Also, few things to note:
- Only call via HTTPS
- Implement a timed authorization token expiration strategy
- Ensure the calling user only has permissions for what they are calling and no more
| Url |
Short Description |
Details Page |
/api/v1/info |
Information about the pimentaCHAT server. |
Link |
/api/v1/directory |
Search by users or channels on all server. |
Link |
/api/v1/shield.svg |
Gets the shield svg(badge) to add in your website. |
Link |
/api/v1/spotlight |
Searches for users or rooms that are visible to the user. |
Link |
/api/v1/statistics |
Statistics about the pimentaCHAT server. |
Link |
/api/v1/statistics.list |
Selectable statistics about the pimentaCHAT server. |
Link |
Assets
| Url |
Short Description |
Details Page |
/api/v1/assets.setAsset |
Set an asset image by name. |
Link |
/api/v1/assets.unsetAsset |
Unset an asset by name |
Link |
Authentication
| Url |
Short Description |
Details Page |
/api/v1/login |
Authenticate with the REST API. |
Link |
/api/v1/login |
Authenticate with google. |
Link |
/api/v1/login |
Authenticate with facebook. |
Link |
/api/v1/login |
Authenticate with twitter. |
Link |
/api/v1/logout |
Invalidate your REST API authentication token. |
Link |
/api/v1/me |
Displays information about the authenticated user. |
Link |
Users
| Url |
Short Description |
Details Page |
/api/v1/users.create |
Create a new user. |
Link |
/api/v1/users.createToken |
Create a user authentication token. |
Link |
/api/v1/users.delete |
Deletes an existing user. |
Link |
/api/v1/users.deleteOwnAccount |
Deletes your own user. |
Link |
/api/v1/users.forgotPassword |
Send email to reset your password. |
Link |
/api/v1/users.generatePersonalAccessToken |
Generate Personal Access Token. |
Link |
/api/v1/users.getAvatar |
Gets the URL for a user’s avatar. |
Link |
/api/v1/users.getPersonalAccessTokens |
Gets the user’s personal access tokens. |
Link |
/api/v1/users.getPreferences |
Gets all preferences of user. |
Link |
/api/v1/users.getPresence |
Gets the online presence of a user. |
Link |
/api/v1/users.getUsernameSuggestion |
Gets a suggestion a new username to user. |
Link |
/api/v1/users.info |
Gets a user’s information, limited to the caller’s permissions. |
Link |
/api/v1/users.list |
All of the users and their information, limited to permissions. |
Link |
/api/v1/users.regeneratePersonalAccessToken |
Regenerate a user personal access token. |
Link |
/api/v1/users.register |
Register a new user. |
Link |
/api/v1/users.removePersonalAccessToken |
Remove a personal access token. |
Link |
/api/v1/users.resetAvatar |
Reset a user’s avatar |
Link |
/api/v1/users.setAvatar |
Set a user’s avatar |
Link |
/api/v1/users.setPreferences |
Set user’s preferences |
Link |
/api/v1/users.update |
Update an existing user. |
Link |
/api/v1/users.updateOwnBasicInfo |
Update basic information of own user. |
Link |
Channels
| Url |
Short Description |
Details Page |
/api/v1/channels.addAll |
Adds all of the users on the server to a channel. |
Link |
/api/v1/channels.archive |
Archives a channel. |
Link |
/api/v1/channels.cleanHistory |
Cleans up a channel’s history, requires special permission. |
Link |
/api/v1/channels.close |
Removes a channel from a user’s list of channels. |
Link |
/api/v1/channels.counters |
Gets channel counters. |
Link |
/api/v1/channels.create |
Creates a new channel. |
Link |
/api/v1/channels.delete |
Removes a channel. |
Link |
/api/v1/channels.files |
Gets a list of files from a channel. |
Link |
/api/v1/channels.getAllUserMentionsByChannel |
Gets all the mentions of a channel. |
Link |
/api/v1/channels.getIntegrations |
Gets the channel’s integration. |
Link |
/api/v1/channels.history |
Retrieves the messages from a channel. |
Link |
/api/v1/channels.info |
Gets a channel’s information. |
Link |
/api/v1/channels.invite |
Adds a user to a channel. |
Link |
/api/v1/channels.join |
Joins yourself to a channel. |
Link |
/api/v1/channels.kick |
Removes a user from a channel. |
Link |
/api/v1/channels.leave |
Removes the calling user from a channel. |
Link |
/api/v1/channels.list |
Retrieves all of the channels from the server. |
Link |
/api/v1/channels.list.joined |
Gets only the channels the calling user has joined. |
Link |
/api/v1/channels.members |
Retrieves all channel users. |
Link |
/api/v1/channels.messages |
Retrieves all channel messages. |
Link |
/api/v1/channels.moderators |
List all moderators of a channel. |
Link |
/api/v1/channels.open |
Adds the channel back to the user’s list of channels. |
Link |
/api/v1/channels.rename |
Changes a channel’s name. |
Link |
/api/v1/channels.roles |
Gets the user’s roles in the channel. |
Link |
/api/v1/channels.setCustomFields |
Sets a channel’s custom fields. |
Link |
/api/v1/channels.setAnnouncement |
Sets a channel’s announcement. |
Link |
/api/v1/channels.setDefault |
Sets whether a channel is a default channel or not. |
Link |
/api/v1/channels.setDescription |
Sets a channel’s description. |
Link |
/api/v1/channels.setJoinCode |
Sets the channel’s code required to join it. |
Link |
/api/v1/channels.setPurpose |
Sets a channel’s description. |
Link |
/api/v1/channels.setReadOnly |
Sets whether a channel is read only or not. |
Link |
/api/v1/channels.setTopic |
Sets a channel’s topic. |
Link |
/api/v1/channels.setType |
Sets the type of room the channel should be. |
Link |
/api/v1/channels.unarchive |
Unarchives a channel. |
Link |
Groups
| Url |
Short Description |
Details Page |
/api/v1/groups.archive |
Archives a private group. |
Link |
/api/v1/groups.close |
Removes a private group from the list of groups. |
Link |
/api/v1/groups.counters |
Gets group counters. |
Link |
/api/v1/groups.create |
Creates a new private group. |
Link |
/api/v1/groups.delete |
Removes a private group. |
Link |
/api/v1/groups.files |
Gets a list of files from a private group. |
Link |
/api/v1/groups.history |
Retrieves the messages from a private group. |
Link |
/api/v1/groups.info |
Gets the information about a private group. |
Link |
/api/v1/groups.invite |
Adds a user to the private group. |
Link |
/api/v1/groups.kick |
Removes a user from a private group. |
Link |
/api/v1/groups.leave |
Removes the calling user from the private group. |
Link |
/api/v1/groups.list |
List the private groups the caller is part of. |
Link |
/api/v1/groups.listAll |
List all the private groups. |
Link |
/api/v1/groups.members |
Gets the users of participants of a private group. |
Link |
/api/v1/groups.messages |
Retrieves all group messages. |
Link |
/api/v1/groups.moderators |
List all moderators of a group. |
Link |
/api/v1/groups.open |
Adds the private group back to the list of groups. |
Link |
/api/v1/groups.rename |
Changes the name of the private group. |
Link |
/api/v1/groups.roles |
Gets the user’s roles in the private group. |
Link |
/api/v1/groups.setAnnouncement |
Sets a group’s announcement. |
Link |
/api/v1/groups.setCustomFields |
Sets private group’s custom fields. |
Link |
/api/v1/groups.setDescription |
Sets a private group’s description. |
Link |
/api/v1/groups.setPurpose |
Sets a private group’s description. |
Link |
/api/v1/groups.setReadOnly |
Sets whether the room is read only or not. |
Link |
/api/v1/groups.setTopic |
Sets a private group’s topic. |
Link |
/api/v1/groups.setType |
Sets the type of room this group will be. |
Link |
/api/v1/groups.unarchive |
Unarchives a private group. |
Link |
Chat
| Url |
Short Description |
Details Page |
/api/v1/chat.delete |
Deletes an existing chat message. |
Link |
/api/v1/chat.getMessage |
Retrieves a single chat message. |
Link |
/api/v1/chat.pinMessage |
Pins a chat message to the message’s channel. |
Link |
/api/v1/chat.postMessage |
Posts a new chat message. |
Link |
/api/v1/chat.react |
Sets/unsets the user’s reaction to an existing chat message. |
Link |
/api/v1/chat.reportMessage |
Reports a message. |
Link |
/api/v1/chat.search |
Search for messages in a channel. |
Link |
/api/v1/chat.starMessage |
Stars a chat message for the authenticated user. |
Link |
/api/v1/chat.sendMessage |
Send new chat message. |
Link |
/api/v1/chat.unPinMessage |
Removes the pinned status of the provided chat message. |
Link |
/api/v1/chat.unStarMessage |
Removes the star on the chat message for the authenticated user. |
Link |
/api/v1/chat.update |
Updates the text of the chat message. |
Link |
/api/v1/chat.getMessageReadReceipts |
Retrieves message read receipts. |
Link |
IM
| Url |
Short Description |
Details Page |
/api/v1/im.close |
Removes a direct message from the list of direct messages. |
Link |
/api/v1/im.counters |
Gets counters of direct messages. |
Link |
/api/v1/im.create |
Create a direct message session with another user. |
Link |
/api/v1/im.history |
Retrieves the messages from a direct message. |
Link |
/api/v1/im.files |
Retrieves a list of files from a direct message. |
Link |
/api/v1/im.members |
Retrieves the users of participants of a direct message. |
Link |
/api/v1/im.messages |
Retrieves the messages from specific direct message. |
Link |
/api/v1/im.messages.others |
Retrieves the messages from any direct message in the server. |
Link |
/api/v1/im.list |
List the direct messages the caller is part of. |
Link |
/api/v1/im.list.everyone |
List all direct message the caller in the server. |
Link |
/api/v1/im.open |
Adds the direct message back to the list of direct messages. |
Link |
/api/v1/im.setTopic |
Sets a direct message topic. |
Link |
Integrations
| Url |
Short Description |
Details Page |
/api/v1/integrations.create |
Creates an integration. |
Link |
/api/v1/integrations.history |
Lists all history of the specified integration. |
Link |
/api/v1/integrations.list |
Lists all of the integrations. |
Link |
/api/v1/integrations.remove |
Removes an integration. |
Link |
Permissions
| Url |
Short Description |
Details Page |
/api/v1/permissions.list |
Lists permissions on the server. |
Link |
/api/v1/permissions.update |
Edits permissions on the server. |
Link |
Roles
| Url |
Short Description |
Details Page |
/api/v1/roles.create |
Create a new role in the system. |
Link |
/api/v1/roles.list |
Gets all the roles in the system. |
Link |
/api/v1/roles.addUserToRole |
Assign a role to an user. |
Link |
Push Token
| Url |
Method |
Short Description |
Details Page |
/api/v1/push.token |
POST |
Saves push token. |
Link |
/api/v1/push.token |
DELETE |
Removes push token. |
Link |
Rooms
| Url |
Short Description |
Details Page |
/api/v1/rooms.cleanHistory |
Cleans up a room’s history, requires special permission. |
Link |
/api/v1/rooms.favorite |
Favorite/Unfavorite room. |
Link |
/api/v1/rooms.get |
Gets rooms. |
Link |
/api/v1/rooms.info |
Gets info from a room. |
Link |
/api/v1/rooms.leave |
Leaves a room. |
Link |
/api/v1/rooms.saveNotification |
Sets the notifications settings of specific channel. |
Link |
/api/v1/rooms.upload/:rid |
Upload a message with attached file. |
Link |
Command Methods
| Url |
Short Description |
Details Page |
/api/v1/commands.get |
Get specification of the slash command. |
Link |
/api/v1/commands.list |
Lists all available slash commands. |
Link |
/api/v1/commands.run |
Execute a slash command in the specified room. |
Link |
Emoji Custom
| Url |
Short Description |
Details Page |
/api/v1/emoji-custom |
List the custom emojis available. |
Link |
Settings
| Url |
Method |
Short Description |
Details Page |
/api/v1/settings |
GET |
Lists all private settings. |
Link |
/api/v1/settings.public |
GET |
Lists all public settings. |
Link |
/api/v1/settings.oauth |
GET |
Return list of all available oauth services. |
Link |
/api/v1/service.configurations |
GET |
Lists all service configurations. |
Link |
/api/v1/settings/:_id |
GET |
Gets a setting. |
Link |
/api/v1/settings/:_id |
POST |
Updates a setting. |
Link |
Subscriptions
| Url |
Method |
Short Description |
Details Page |
/api/v1/subscriptions.get |
GET |
Get all subscriptions. |
Link |
/api/v1/subscriptions.getOne |
GET |
Get the subscription by room Id. |
Link |
/api/v1/subscriptions.read |
POST |
Mark a room as read. |
Link |
/api/v1/subscriptions.unread |
POST |
Mark messages as unread. |
Link |
Video Conference
| Url |
Short Description |
Details Page |
/api/v1/video-conference/jitsi.update-timeout |
Updates the timeout of Jitsi video conference in a channel. |
Link |
Voice Calls
| Url |
Short Description |
Details Page |
/api/v1/voice.call |
Send a push notification based on push settings. |
Link |
/api/v1/voice.call.feedback |
Send feedback about actions performed on calls. |
Link |
/api/v1/voice.call.ping |
Send a ping to server to indicate that user is online. |
Link |
/api/v1/voice.call.history |
List calls from a room |
Link |
