API Resource Endpoints

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

Activities

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

Attachments

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 (OP only)
DELETE /api/attachments/:attachment_id destroy an attachment

Authentication

Resource Description
POST /api/authentication determine if the user has correct credentials

Badges

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

Client devices

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

Comments

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

Content filters

Resource Description
GET /api/content_filters get a list of content filters in the current community

Conversations

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

Custom fields

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

External systems

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

Flags

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

Followers

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

Following

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

Group memberships

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 priviledge 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)

Groups

Resource Description
GET /api/groups/:group_id/members get a list of members of a group that the user has access to
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
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

Likes

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

Media files

Resource Description
GET /api/media_files/:id/:thumbnail/:filename retrieve the contents of a media file (OP only)

Members

Resource Description
GET /api/conversations/:conversation_id/members list all conversation members
POST /api/conversations/:conversation_id/members add new members to the referenced conversation
DELETE /api/conversations/:conversation_id/members/me remove the authorized user from the referenced conversation

Messages

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

Notifications

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

Polls

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

Reach extensions

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

Remarks

Resource Description
POST /api/conversations/:conversation_id/remarks create a new remark

Search

Resource Description
GET /api/search/suggestions get suggestions for a query. Intended for use as autocomplete suggestions

Streams

Resource Description
GET /api/streams get a list of this user's streams

Tags

Resource Description
GET /api/tags/:id get information for a given tag

Tenants

Resource Description
GET /api/community_info get information about current community

Thanks

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

Topics

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

Users

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/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