socialmod's REST API allows to programatically submit video/text and images for moderation, check on their status, and receive callbacks when that changes.

There's no reason to reinvent the wheel though - there are a number of existing open source libraries that integrate with socialmod listed on the right.
We still recommend reading through this document though, especially the integration section.

You should use the API key below to authenticate all your requests. If you need a new key to be generated, please contact us.

In socialmod, an 'item' is a piece of moderation, such as image, text or video content.

The API is asynchronous, so when an item is created it won't be moderated immediately. You'll have to check back later, or receive callbacks, to find out when it has been moderated. Remember, you can always use the dmh option on an item, which will take an item down temporarily if it doesn't get moderated within a specific time period.

We support active moderation too. Users visiting your site can flag content, which can then be sent here for moderation. If multiple users flag the same content, you can temporarily take it down using the flag_take_down option.

This documents consists of the following sections:

• Items - submit/fetch/flag and callbacks
• Integration - site integration and embedding
• Dashboard - moderation stats

Your API key

Please log in to see your API key. In this document the dummy value of '00000000-0000-0000-0000-000000000000' will be used.

Authentication

Provide an authorization header containing your API key.

  Authorization: 00000000-0000-0000-0000-000000000000

Items

Get all Items

Specify the return format by putting the format extension on the url, such as /items.xml or /items.json (default is XML).

  GET: /items
  Host: api.socialmod.com
  Authorization: 00000000-0000-0000-0000-000000000000

Fetch moderated items

This will return all items that were moderated since the last time you called this url.

  GET: /items/sync
  Host: api.socialmod.com
  Authorization: 00000000-0000-0000-0000-000000000000

Fetch item by id

  GET: /items/id
  Host: api.socialmod.com
  Authorization: 00000000-0000-0000-0000-000000000000

Fetch item by custom_id

  GET: /items/custom/custom_id
  Host: api.socialmod.com
  Authorization: 00000000-0000-0000-0000-000000000000

Flagging an item

You can flag an item multiple times (if say your moderation is being run by the community) which raises the profile of particular items.
Each time you send the following request, the item's flag count gets incremented.

  POST: /items/id/flag
  Host: api.socialmod.com
  Authorization: 00000000-0000-0000-0000-000000000000

Submitting an item for moderation

There are four main types of moderation:

• Image moderation
• Video moderation
• Text moderation
• HTML moderation

When you submit an item for moderation you need to specify a mime, and either a data attribute, or a src attribute.
You need to include the src attribute if the item is an image or video.
You need to include the data attribute if the item is text or HTML.

If you're specifying the src attribute, it needs to be a publicly accessible address over http.
For video moderation, we supply the player. You just need to specify the address of a flv file.

For text moderation, the data is completely escaped - so don't include any HTML in it.
For HTML moderation, we sanitize the data and strip out certain tags.
At the moment, we don't limit the length of data - however we do ask that you keep it to a reasonable length so that a moderator can quickly vet it.

If your parameters are XML, or JSON, then you'll need to call /items.xml or /items.json respectively.

  POST: /items
  Host: api.socialmod.com
  Authorization: 00000000-0000-0000-0000-000000000000
  
  parameters

Here's an example of URL encoded form parameters:

  item[custom_id]=foo&item[data]=Lots%20of%20text

Here's an XML example of the parameters:

 <item>
   <custom_id>foo</custom_id>
   <src>http://www.example.com/public/vid_23223.flv</src>
   <mime>video/x-flv</mime>
 </item>

And a JSON example:

 {
   "item": {
     "custom_id": "foo",
     "src": "http://www.example.com/public/vid_23223.png",
     "mime": "image/png"
   }
 }

Item attributes

Click on specific attributes for more information (show all)

Callbacks

You can get HTTP post callbacks when an item has been moderated by specifying a callback_url, either when you create an item, or globally in settings.
At the moment, If the request doesn't return a HTTP 200, we'll try again 10 times every so often.
We'll send a HTTP POST request to this URL containing the following parameters:

Integrate socialmod into your website

You can integrate socialmod into your site - so trusted members of your existing community can moderate content.
To do this, you need to create socialmod users - and then either embed socialmod into your site using an iframe, or forward users onto this site.

Note: you should only be using this part of the API if your plan doesn't include automated moderation.

Create users

You can create users using the API so they don't need to register separately on the site.

  GET: /users
  Host: api.socialmod.com
  Authorization: 00000000-0000-0000-0000-000000000000
  
  parameters

The parameters that need to be included are:

• first_name
• last_name
• email

As with the rest of the API, you can encode these parameters as XML/JSON or form encoded entities. Here's an XML example:

 <user>
   <first_name>foo</first_name>
   <last_name>foo</last_name>
   <email>foo@example.com</email>
 </user>

When you create a user you'll receive an User object in response. Contained in that User object will be an auth_key attribute, which you can use to authenticate users without having them logging into the system.

Embedding

You can use an iframe to embed socialmod directly into your site. The URL needs to contain the users 'auth_key' so they aren't prompted to login.
It's recommended that the iframe is at least 550px high, so users can use the moderation interface properly.

  <iframe width="100%" height="550px" src="http://www.socialmod.com/moderate?auth_key=foo" />

Redirecting

The alternative to embedding is to redirect the user to: http://www.socialmod.com/moderate?auth_key=foo

Getting stats from the Dashboard

You can get the same stats that you can see in the Dashboard via the API. Keep in mind though, that these stats are only valid for the last 30 days.

  GET: /dashboard
  Host: api.socialmod.com
  Authorization: 00000000-0000-0000-0000-000000000000

The attributes returned are:

Information

Retrieval

Submittal

Available libraries

Questions?