The SocialEngine Cloud API is still a work in progress. We'll be updating these docs as we roll out more functionality in the coming weeks.
In order to access the API, you will need to use the API URL and API Key provided from the Settings > Site Info page in your admin panel. An API URL is bound to an API Key, and must be included as a parameter when making requests to API resources.
Example GET Request using curl
curl {{API URL}}/{{ROUTE}}?api_key={{API KEY}}
Example POST Request using curl
curl {{API URL}}/{{ROUTE}} -d "api_key={{API KEY}}"
Rate limits in the beta version of the API are applied on a per IP address basis. Each IP address is allowed to make up to 3 requests per second, and a total of 120 requests per minute.
Code | Text | Description |
---|---|---|
200 | OK | Success! |
304 | Not Modified | There was no new data to return. |
400 | Bad Request | The request was invalid. |
401 | Unauthorized | Authentication credentials were missing or incorrect. |
403 | Forbidden | The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why. |
404 | Not Found | The URI requested is invalid or the resource requested, such as a member, does not exists. Also returned when the requested format is not supported by the requested method. |
406 | Not Acceptable | Returned when an invalid format is specified in the request. |
409 | Missing Parameter | Returned when a request cannot be served due to a missing required parameter. |
429 | Too Many Requests | Returned when a request cannot be served due to the application's rate limit having been exhausted. |
500 | Internal Server Error | Something is broken. Please contact the SE Cloud team so that we can investigate. |
502 | Bad Gateway | API is down or being upgraded. |
503 | Service Unavailable | Servers are up, but overloaded with requests. Try again later. |
504 | Gateway timeout | Our servers are up, but the request couldn't be serviced due to some failure within our stack. Try again later. |
Name | Description |
---|---|
member_id | The numerical identifier for a member account |
full_name | A member's full name |
first_name | A member's first name |
last_name | A member's last name |
A member's email address | |
website | A member's website URL |
about_me | A short description about a member |
gender | A member's gender |
country | A member's country |
approved | Used to denote members that have been given approval to access a site. This setting works in conjunction with the Require Approval setting available from the Admin > Settings > Members page. When set to 0, members will not have access to a site, until an admin or moderator approves the account. If Require Approval is not enabled, this value defaults to 1 for new members. |
verified | Used to denote members that have verified their account. |
featured | Used to denote members that have been marked as featured. |
flagged | Used to denote members that were reported as being abusive or spam. |
date_created | The date the member signed up or was created. |
total_posts | The number of posts created by a member. |
total_comments | The number of comments created by a member. |
total_followers | The number of members following a given member. |
total_following | The number of members a given member is following. |
total_likes | The number of posts and comments liked by a member. When Voting is set to Up/Down Votes from the Admin > Settings > Posts page, this referrs to the total number of posts and comments up voted by a member. |
total_dislikes | The number of posts and comments disliked by a member. When Voting is set to Up/Down Votes from the Admin > Settings > Posts page, this referrs to the total number of posts and comments down voted by a member. |
total_likes_received | The number of times other members have liked a member's posts or comments. |
total_comments_recieved | The number of times other members have commented on a given member's posts. |
score | A member's popularity, calculated by taking the difference of total likes/up votes and dislikes/down votes on a member's posts and comments. (i.e. likes on posts + likes on comments - dislikes on posts - dislikes on comments) |
date_created | The date a member created their account. |
Name | Description |
---|---|
post_id | The numerical identifier for post. |
member_id | The numerical identifier for the member account associated with the post. |
type | One of the 4 distinct post types: image, link, topic or video. |
category_id | The numerical identifier for a category associated with the post. |
title | Title of the post |
description | Text description of the post, or the message body for the topic. |
link | This is the original URL for a shared link, image or video. |
thumb | This is the URL to the thumbnail image for a link, image or video. |
thumb_large | This is the URL to the a larger version of the thumbnail image. |
thumb_large_width | Describes the width of the image and is used only with the image post type. |
thumb_large_height | Describes the height of the image and is used only with the image post type. |
video_code | This is the URL unique identifier for Youtube or Vimeo videos. |
video_type | Denotes which service the video is from: youtube or vimeo. |
total_likes | The number of times a post was liked or up voted. |
total_dislikes | The number of times a post was disliked or down voted. |
total_comments | The number of times a post was commented on, not including replies. |
total_comments_all | The number of times a post was commented on including replies. |
total_views | The number of times a post was viewed. |
date_created | The UTC 00:00 date and time a post was created in the ISO 8601 standard. |
flagged | Used to denote a post that was reported as being abusive or spam. |
flag_count | The number of times a post was reported. |
featured | Used to denote a post that has been highlighted by an admin or moderator. |
closed | Used to denote a post that can no longer be commented on. |
Name | Description |
---|---|
message_id | The numerical identifier for a message |
message | The body text of a message |
sender | A member object corresponding to the person who sent the message. see Member Object |
reciever | A member object corresponding to the person who recieved the message. see Member Object |
date_created | The date the message was created |
Provides an auth token for member account.
Parameters | |
---|---|
api_key (required) | The API Key for a site. This can be found on the Settings > Site Info page in the admin panel |
member_id (required) | The numerical identifier for a member account. |
Example Request
curl http://site.api.socialengine.com/auth/token -d "api_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&member_id=1"
Response
{
"token" : "751c169c28054a1eb7488c1791481463"
}
Returns a paginated list of members for a community.
Parameters | |
---|---|
items_per_page (optional) | The number of members to return with the request, up to a maximum of 100. Defaults to 20. |
page (optional) | The current page in the result set. Defaults to 1 |
Response
{
total : 1000,
items_per_page : 20,
offset : 1,
data : [
{ "member_id" : "1", "avatar" : "…", … },
{ "member_id" : "2", "avatar" : "…", … },
{ "member_id" : "3", "avatar" : "…", … },
…
]
}
Example Request
curl http://site.api.socialengine.com/members?items_per_page=20&page=1
Response
{
total : 1000,
items_per_page : 20,
offset : 1,
data : [
{ "member_id" : "1", "avatar" : "…", … },
{ "member_id" : "2", "avatar" : "…", … },
{ "member_id" : "3", "avatar" : "…", … },
…
]
}
Returns a single member account, specified by the member_id parameter.
Parameters | |
---|---|
member_id (required) | The numerical identifier for a member account |
Example Request
curl http://site.api.socialengine.com/member/1
Response
{
data : {
"member_id" : "1",
"full_name" : "Shaun Harding",
"first_name" : "Shaun",
"last_name" : "Harding",
"website" : "",
"about_me" : "All your APIs are belong to me.",
"gender" : "male",
"country" : " … ",
"approved" : true,
"verified" : true,
"enabled" : true,
"featured" : false,
"flagged" : false,
"total_posts" : 79,
"total_comments" : 104,
"total_followers" : 8,
"total_following" : 8,
"total_likes" : 0,
"total_dislikes" : 0,
"total_likes_received" : 8,
"total_comments_recieved" : 48,
"score" : 24
}
}
Returns a paginated list of a member’s followers
Parameters | |
---|---|
member_id (required) | The numerical identifier for a member account |
items_per_page (optional) | The number of followers to return with the request, up to a maximum of 100. Defaults to 20. |
offset | The member_id to start from |
Example Request
curl http://site.api.socialengine.com/member/1/followers?member_id=1&items_per_page=20&offset=1
Response
{
total : 8,
items_per_page : 20,
offset : 1,
data : [
{ "member_id" : "1", "full_name" : " … ", "avatar" : " … ", … },
{ "member_id" : "2", "full_name" : " … ", "avatar" : " … ", … },
{ "member_id" : "3", "full_name" : " … ", "avatar" : " … ", … },
…
]
}
Fetches a paginated list of members that another member (member_id) is following.
Parameters | |
---|---|
member_id (required) | The numerical identifier for a member account |
items_per_page | The number of members being followed to return with the request, up to a maximum of 100. Defaults to 20. |
offset | The member_id to start from |
Example Request
curl http://site.api.socialengine.com/member/1/following?member_id=1&items_per_page=20&page=1
Response
{
total : 8,
items_per_page : 20,
offset : 1,
data : [
{ "member_id" : "1", "full_name" : " … ", "avatar" : " … ", … },
{ "member_id" : "2", "full_name" : " … ", "avatar" : " … ", … },
{ "member_id" : "3", "full_name" : " … ", "avatar" : " … ", … },
…
]
}
Returns a paginated list of a member's message threads
Parameters | |
---|---|
token | Authentication token for a member. See the section on Authentication |
items_per_page | The number of messages to return with the request, up to a maximum of 100. Defaults to 20. |
offset | Specifies the offset of the first thread to return |
Example Request
curl http://site.api.socialengine.com/messages?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&items_per_page=20&offset=0
Response
{
total : 3,
items_per_page : 20,
offset : 0,
data : [
{ "message_id" : "1", "message" : " … ", "sender" : {}, "reciever" : {}, "date_created" : "2012-11-16T21:37:14.307Z" },
{ "message_id" : "3", "message" : " … ", "sender" : {}, "reciever" : {}, "date_created" : "2012-11-16T21:37:14.307Z" },
{ "message_id" : "3", "message" : " … ", "sender" : {}, "reciever" : {}, "date_created" : "2012-11-16T21:37:14.307Z" },
]
}
Returns a paginated list of messages exchanged between 2 members
Parameters | |
---|---|
token | Authentication token for a member. See the section on Authentication |
member_id (required) | The numerical identifier for a member account |
items_per_page | The number of messages to return with the request, up to a maximum of 100. Defaults to 20. |
offset | Specifies the offset of the first thread to return |
Example Request
curl http://site.api.socialengine.com/message/2?token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&items_per_page=20&offset=0
Response
{
total : 3,
items_per_page : 20,
offset : 0,
data : [
{ "message_id" : "1", "message" : " … ", "sender" : {}, "reciever" : {}, "date_created" : "2012-11-16T21:37:14.307Z" },
{ "message_id" : "3", "message" : " … ", "sender" : {}, "reciever" : {}, "date_created" : "2012-11-16T21:37:14.307Z" },
{ "message_id" : "3", "message" : " … ", "sender" : {}, "reciever" : {}, "date_created" : "2012-11-16T21:37:14.307Z" },
]
}
Returns a single post, specified by the post_id
parameter.
Parameters | |
---|---|
post_id (required) | The numerical identifier for the desiered post |
Example Request
curl http://site.api.socialengine.com/post/1
Response
{
data: {
post_id: 3,
member_id: 1,
member : {
"member_id" : "1",
"full_name" : "Shaun Harding",
"first_name" : "Shaun",
"last_name" : "Harding",
"website" : "",
"about_me" : "All your APIs are belong to me.",
"gender" : "male",
"country" : " … ",
"approved" : true,
"verified" : true,
"enabled" : true,
"featured" : false,
"flagged" : false,
"total_posts" : 79,
"total_comments" : 104,
"total_followers" : 8,
"total_following" : 8,
"total_likes" : 0,
"total_dislikes" : 0,
"total_likes_received" : 8,
"total_comments_recieved" : 48,
"score" : 24
},
type: "topic",
category_id: 0,
category_name: null,
title: "My topic #3",
description: "This is topic #3",
link: null,
thumb: null,
thumb_large: null,
thumb_large_width: 0,
thumb_large_height: 0,
video_code: null,
video_type: null,
total_views: 1,
total_likes: 0,
total_dislikes: 0,
total_comments: 0,
total_comments_all: 0,
flagged: 0,
flag_count: 0,
featured: 0,
closed: 0,
date_created: "2012-07-23T22:03:22.000Z"
}
}
Returns a paginated list of posts for a community sorted by most popular.
Parameters | |
---|---|
category_id (optional) | The numerical identifier for a category |
items_per_page (optional) | The number of posts to return with the request, up to a maximum of 100. Defaults to 20. |
offset (optional) | The offset of the first post to return |
Example Request
curl http://site.api.socialengine.com/posts/hot
Response
{
total : 1000,
items_per_page : 20,
offset : 1,
data : [
{ "post_id" : "1", "member_id" : "1", … },
{ "post_id" : "2", "member_id" : "2", … },
{ "post_id" : "3", "member_id" : "3", … },
…
]
}
Returns a paginated list of posts for a community, sorted by their creation date in descending order.
Parameters | |
---|---|
category_id (optional) | The numerical identifier for a category |
items_per_page (optional) | The number of posts to return with the request, up to a maximum of 100. Defaults to 20. |
offset (optional) | The offset of the first post to return |
Example Request
curl http://site.api.socialengine.com/posts/newest
Response
{
total : 1000,
items_per_page : 20,
offset : 1,
data : [
{ "post_id" : "1", "member_id" : "1", … },
{ "post_id" : "2", "member_id" : "2", … },
{ "post_id" : "3", "member_id" : "3", … },
…
]
}
Returns a paginated list of posts for a community, sorted by their rating score, in descending order.
Parameters | |
---|---|
category_id (optional) | The numerical identifier for a category |
items_per_page (optional) | The number of posts to return with the request, up to a maximum of 100. Defaults to 20. |
offset (optional) | The offset of the first post to return |
Example Request
curl http://site.api.socialengine.com/posts/top
Response
{
total : 1000,
items_per_page : 20,
offset : 1,
data : [
{ "post_id" : "1", "member_id" : "1", … },
{ "post_id" : "2", "member_id" : "2", … },
{ "post_id" : "3", "member_id" : "3", … },
…
]
}
Returns a paginated list of posts for a member, sorted by their creation date in descending order.
Parameters | |
---|---|
items_per_page (optional) | The number of posts to return with the request, up to a maximum of 100. Defaults to 20. |
page (optional) | The current page in the result set. Defaults to 1 |
Example Request
curl http://site.api.socialengine.com/posts/member?member_id=1
Response
{
total : 1000,
items_per_page : 20,
offset : 1,
data : [
{ "post_id" : "1", "member_id" : "1", … },
{ "post_id" : "2", "member_id" : "2", … },
{ "post_id" : "3", "member_id" : "3", … },
…
]
}
Creates a one-time use token to log a user into SocialEngine Cloud from another site.
When the create flag is set and the user doesn't exist, this endpoint will create a new account before returning a token. The URL should be http://(site).onsocialengine.com/api/sso .
Note: If a user already exists, it will simply return a token to log the existing user in.
Parameters | |
---|---|
apiKey (required) | The API Key for your community. Found on the "Sites Info" page. |
user[user_id] (optional) | SocialEngine Cloud User ID of the member to login. |
user[email] (required for create) | The email address for the member to login. |
user[displayname] (optional) | The display name for the member (used only for create). |
create (optional) | Set to 1 to create a user, if not found. Defaults to 0 |