The Socialcast REST API provides programmatic access to the same functionality that is available via your community's Socialcast website. You can write a Socialcast Client Application in any programming language. This documentation contains examples of how to invoke every endpoint using cURL.
The community used in the examples is our demo community: https://demo.socialcast.com
Once you are ready to start coding, replace "demo.socialcast.com" with the location of your community. Ex: "openwebstandards.socialcast.com"
All of the endpoints require authentication as seen above. Details at: HTTP Basic Authentication
| Resource | Description |
|---|---|
| GET /api/conversations/:conversation_id/activities | get page of activities for a conversation |
| GET /api/conversations/:conversation_id/activities/:id | get a specific activity item |
| Resource | Description |
|---|---|
| GET /api/users/:user_id/attachments | paginated list of attachments for a group or user |
| POST /api/attachments | create an attachment - limit 100MB. Requires Content-Type: multipart/form-data. Administrator can decrease the maxmimum attachment size |
| GET /api/attachments/:attachment_id | redirect to attachment |
| GET /api/attachments/:attachment_id/:thumbnail/:filename | retrieve the contents of an Attachment |
| DELETE /api/attachments/:attachment_id | destroy an attachment |
| Resource | Description |
|---|---|
| POST /api/authentication | determine if the user has correct credentials |
| Resource | Description |
|---|---|
| GET /api/badges/:id | get a list of all enabled badges received by a user |
| GET /api/badges/:id/messages | gets the most recent messages for the specified badge |
| Resource | Description |
|---|---|
| POST /api/groups/:group_id/chat_messages | create a new chat message |
| GET /api/groups/:group_id/chat_messages | get a list of chat messages for a group |
| Resource | Description |
|---|---|
| GET /api/client_devices | show all devices registered to the current logged in user |
| PUT /api/client_devices | register a device to the current logged in user. Client devices are referenced by registration_id and notification_type |
| DELETE /api/client_devices | unregister a device. Client devices are referenced by registration_id and notification_type |
| Resource | Description |
|---|---|
| POST /api/messages/:message_id/comments | create a new comment |
| GET /api/messages/:message_id/comments/:id | get an individual comment |
| GET /api/messages/:message_id/comments | get a list of comments associated with a message |
| DELETE /api/messages/:message_id/comments/:id | delete a comment attached to a particular message |
| PUT /api/messages/:message_id/comments/:id | update an existing comment on a message. Only the comment owner can perform this operation |
| Resource | Description |
|---|---|
| GET /api/content_filters | get a list of content filters in the current community |
| Resource | Description |
|---|---|
| GET /api/conversations/:id | retrieve a single conversation |
| PUT /api/conversations/:id | update a conversation |
| GET /api/conversations | get a list of conversations that this user has access to |
| POST /api/conversations | create a new conversation |
| POST /api/conversations/:id/acknowledge | Mark messages in a conversation as read |
| POST /api/conversations/acknowledge_all | Mark all remarks in all of this user's conversations as read. This will clear the unread flag on all of their conversations |
| PUT /api/conversations/:id/hide | Hide a 1:1 conversation. This will hide a 1:1 conversation and remove it from the nav. The conversation will still be available under the hidden filter on the messages page. |
| PUT /api/conversations/:id/unhide | This will unhide a 1:1 conversation for a specific user |
| Resource | Description |
|---|---|
| GET /api/custom_fields | get a list of custom fields defined for the current community |
| GET /api/custom_fields/:id | retrieve a single custom field |
| POST /api/custom_fields | create a new custom field |
| PUT /api/custom_fields/:id | modify an existing custom field |
| DELETE /api/custom_fields/:id | destroy a custom field |
| Resource | Description |
|---|---|
| GET /api/external_systems | get a list of external_systems |
| GET /api/external_systems/:external_system_id | get a single external_system for the authenticated reach admin |
| POST /api/external_systems | create an external system for the authenticated reach admin |
| PUT /api/external_systems/:external_system_id | update an external system for the authenticated reach admin |
| DELETE /api/external_systems/:external_system_id | deactivate an external_system |
| POST /api/external_systems/authentication | verifies authentication of an external system |
| Resource | Description |
|---|---|
| POST /api/messages/:message_id/flags | flag or bookmark a message |
| DELETE /api/messages/:message_id/flags/:flag_id | remove flag or bookmark from a message |
| Resource | Description |
|---|---|
| GET /api/users/:user_id/followers | get a list of a user's followers |
| POST /api/users/:user_id/followers | the authenticated user will follow user_id |
| DELETE /api/users/:user_id/followers/:my_user_id | the authenticated user or my_user_id will unfollow user_id |
| Resource | Description |
|---|---|
| GET /api/users/:user_id/following | get a list of users that a user is following |
| DELETE /api/users/:user_id/following/:id | unfollow a user |
| Resource | Description |
|---|---|
| POST /api/groups/:group_id/membership_requests | request membership into a group that allows access requests |
| DELETE /api/groups/:group_id/membership_request | cancels a pending group membership request |
| Resource | Description |
|---|---|
| GET /api/group_memberships | get a list of groups that the current user is a member of |
| GET /api/groups/:group_id/memberships | get a list of membership records for a group that the user has access to |
| POST /api/groups/:group_id/memberships | add a member to a group (group admin privilege required) |
| POST /api/groups/:group_id/memberships/add_members | add or invite one or more members to a group (group admin privilege required) |
| PUT /api/groups/:group_id/memberships/:membership_id | change a member's roles in a group (group admin privileges required) |
| DELETE /api/groups/:group_id/memberships | remove member from a group (group admin privileges required) |
| Resource | Description |
|---|---|
| GET /api/groups/:group_id/members | Get a list of members for a group visible to the user. Can request admins only (role=admin) for private groups allowing access requests. |
| GET /api/groups | get a list of groups viewable by the authenticated user |
| GET /api/users/:user_id/groups | groups which are viewable by the authenticated user and user_id is a member of |
| GET /api/groups/:group_id/messages | get a list of messages in a group |
| GET /api/groups/mutual | get a list of groups shared between two users |
| GET /api/groups/:group_id | get a single group |
| POST /api/groups | create a group for the authenticated user |
| PUT /api/groups/:group_id | update a group for the authenticated user |
| DELETE /api/groups/:group_id | destroy a group |
| DELETE /api/groups/:group_id/archive | archive a group |
| POST /api/groups/:group_id/join | join a group |
| POST /api/groups/:group_id/leave | leave a group |
| PATCH /api/groups/:group_id/chat_messages | update last_viewed_at for a group chat stream |
| GET /api/groups/search | get a list of groups matching the search term q |
| POST /api/groups/:id/hide_message | hides a message from the group stream (only usable by a group admin) |
| GET /api/groups/pinned | get a list of groups that have been pinned/favorited by the user |
| Resource | Description |
|---|---|
| POST /api/webhooks/:webhook_identifier/:webhook_secret | create a new message in your tenant using an integration setup on a group |
| Resource | Description |
|---|---|
| GET /api/messages/:message_id/likes | get a list of users who have liked the message |
| GET /api/messages/:message_id/comments/:comment_id/likes | get a list of users who have liked the comment |
| POST /api/messages/:message_id/likes/:comment_id/likes | like a message |
| POST /api/messages/:message_id/comments/:comment_id/likes/:comment_id/likes | like a comment |
| DELETE /api/messages/:message_id/likes/:likes_id | unlike a message |
| DELETE /api/messages/:message_id/comments/:comment_id/likes/:comment_id/likes/:likes_id | unlike a comment |
| GET /api/messages/:message_id/likes/:comment_id/likes/:id | show an existing like on a message |
| GET /api/messages/:message_id/comments/:comment_id/likes/:comment_id/likes/:id | show an existing like on a comment |
| Resource | Description |
|---|---|
| GET /api/media_files/:id/:thumbnail/:filename | retrieve the contents of a media file |
| Resource | Description |
|---|---|
| GET /api/meetings | Get a list of all the available meeting types supported for your tenant |
| POST /api/meetings | Create a meeting for an authenticated user |
| Resource | Description |
|---|---|
| GET /api/messages | get a list of messages |
| GET /api/streams/:stream_id/messages | get a list of messages from the specified stream |
| GET /api/external_systems/:external_system_id/messages | get a list of messages from the specified external system |
| GET /api/users/:user_id/messages | get a list of messages related to the specified user |
| GET /api/messages/search | search for messages matching a phrase |
| GET /api/messages/:message_id | fetch a specific message |
| PUT /api/messages/:message_id | update a message |
| DELETE /api/messages/:message_id | destroy a message |
| POST /api/messages | create a new message |
| POST /api/streams/:stream_id/messages | create a new message for the specified stream |
| POST /api/external_systems/:external_system_id/messages | create a new external system message from an authorized admin user |
| Resource | Description |
|---|---|
| GET /api/notifications | get notifications directed toward the current user |
| PUT /api/notifications/mark_all_read | mark all notifications as read |
| POST /api/notifications/:id/read | mark a single notifications as read |
| Resource | Description |
|---|---|
| POST /api/polls | create a new poll without a message |
| GET /api/polls/:poll_id | get information about a poll with poll_id |
| GET /api/messages/:message_id/poll | get information about a poll with message_id |
| POST /api/polls/:poll_id/respond | respond to a poll with poll_id |
| POST /api/messages/:message_id/poll/respond | respond to a poll with message_id |
| Resource | Description |
|---|---|
| GET /api/reach_extensions | get a list of reach_extensions |
| GET /api/reach_extensions/:reach_extension_id | get a single reach_extension for the authenticated reach admin |
| POST /api/reach_extensions | create an reach_extension for the authenticated reach admin |
| PUT /api/reach_extensions/:reach_extension_id | update a reach_extension for the authenticated reach admin |
| Resource | Description |
|---|---|
| POST /api/conversations/:conversation_id/remarks | create a new remark |
| Resource | Description |
|---|---|
| GET /api/search/suggestions | get suggestions for a query. Intended for use as autocomplete suggestions |
| Resource | Description |
|---|---|
| GET /api/streams | get a list of this user's streams |
| GET /api/streams/primary | get the user's primary stream |
| Resource | Description |
|---|---|
| GET /api/tags/:id | get information for a given tag |
| Resource | Description |
|---|---|
| GET /api/community_info | get information about current community |
| Resource | Description |
|---|---|
| GET /api/thanks | get a list of all thanks for the current tenant or all by a specific user |
| POST /api/thanks | send thanks to a recipient |
| Resource | Description |
|---|---|
| POST /api/topics | create a new topic |
| GET /api/topics/:topic_id | get a list of messages for a given topic |
| PUT /api/topics/:topic_id | update a topic |
| GET /api/topics/search | get a list of topics that match the given search criteria |
| GET /api/topics/:topic_id/contributors | get a list of users who have contributed to a topic |
| Resource | Description |
|---|---|
| GET /api/users | get a list of users for the current community |
| GET /api/users/:user_id | show information for a user |
| GET /api/users/:user_id/employees | list users for whom the user is the manager |
| GET /api/users/search | search for users in your community |
| GET /api/users/suggest | suggest users in your community for autocompletion |
| PUT /api/users/:user_id | update the authenticated user or another user as a community admin |
| POST /api/users | create a user as a community admin |
| DELETE /api/users/:user_id | deactivate a user |
| GET /api/userinfo | get information on current user |
| GET /api/users/company_login/:company_login | show information for a user |
| Resource | Description |
|---|---|
| GET /api/groups/:group_id/webhooks | |
| POST /api/groups/:group_id/webhooks |
