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

• The demo community's data gets refreshed every day
• With demo you can use the credential: emily@socialcast.com/demo

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 membership requests

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

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 privilege required)
POST /api/groups/:group_id/memberships/add_members	add 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)

Groups

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

Incoming webhook

Resource	Description
POST /api/webhooks/:webhook_identifier/:webhook_secret	create a new message in your tenant using an integration setup on a group

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

Webhook external systems

Resource	Description
GET /api/groups/:group_id/webhooks
POST /api/groups/:group_id/webhooks