Welcome

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

Miscellaneous Information

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