Menu

SocialEngine API Documentation

SocialEngine Cloud API

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.

API Access

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

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.

API Response Codes

HTTP Status Codes

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.

API Object Specification

Member Object

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

Post Object

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.

Message Object

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

API Methods

Authentication

POST /auth/token

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

Members

GET /members

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" : "…", … },
    …
  ]
}

GET /member/:member_id

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

GET /member/:member_id/followers

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" : " … ", … },
    …
  ]
}

GET /member/:member_id/following

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" : " … ", … },
    …
  ]
}

Messages

GET /messages

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" },
  ]
}

GET /message/:member_id

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" },
  ]
}

Posts

GET /post/:post_id

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

GET /posts/hot

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", … },
    …
  ]
}

GET /posts/newest

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", … },
    …
  ]
}

GET /posts/top

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", … },
    …
  ]
}

GET /posts/member

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", … },
    …
  ]
}

Single Sign-On (SSO)

POST /api/sso

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

SocialEngine Cloud

SocialEngine PHP

Try SocialEngine Cloud