→  Latest News

• Initial Release. This document is a work in progress. Follow updates at the Disqus Blog.

  by Jason Yan on October 29th, 2007

→  Introduction

Disqus provides an Application Programming Interface (API) for users to interact with the Disqus backend. This document serves as a reference for developers to build extensions upon the Disqus API. As of this writing, the API is at version 1 and only currently supports read operations. Visit the Disqus Developers Forum for support.

→  Basic Concepts

The Disqus API provides a RESTful interface to the Disqus backend.

Requests

All API methods accept their parameters in the query string of a GET request. All requests MUST end with a trailing slash (before the query string). Requests are currently throttled per IP address. In the event that you are throttled, the data is retrieved from a cache of the previous request. Slug parameters are human-readable unique identifiers (usually a string shortword for describing an object, such as a thread's title).

Responses

All responses are UTF-8 encoded. A status code of 200 represents a successful request, 400 represents an invalid parameter (an error message is provided in the response as err.msg), and 404 represents an object for a parameter was not found (error message in err.msg).

Response Types

All API methods accept a parameter "response_type". The response type parameter allows you to choose which serialized format you would like to receive your response in. At the moment, valid options for this parameter are "php" and "json" (with "xml" coming soon).

"json" provides a plain-text representation of the response based on a subset of JavaScript.

"php" provides a plain-text representation of the response that may be used with the PHP unserialize function. Other languages have third-party languages to support PHP serialization.

1. C#: Sharp Serialization Library
2. Flash/ActionScript: SerializerClass
3. Perl: PHP-Serialization
4. Python: PHP Serialize
5. Ruby: Ruby PHP Serializer

→  API Methods

get_posts

Get posts for a thread. For threaded posts (if flat is false), posts are returned in thread-order.

URL: http://disqus.com/api/v1/get_posts/

Parameters:

1. forum_url (required)
   Disqus forum URL
2. One of the following are required:
   thread_id — OR — thread_slug — OR — thread_url
   Used to determine which to thread to look up.
   - thread_id is a numeric unique identifier for the thread.
   - thread_slug is the human-readable unique identifier (slug)
   - thread_url is the Link attached to the Thread.
   If multiple parameters are provided, the order of precedence is: thread_id, thread_slug, thread_url.
3. category_id (optional, defaults to General category)
   You may specify which numeric category ID new threads are to be created in. If the thread already exists or a thread_url is not provided, this parameter is ignored. (You may look up the numeric ID through the URL, e.g., http://__FORUM_URL__.disqus.com/c/NN/, where NN is the numeric ID).
4. response_type (optional, defaults to 'json')
   Response format. Valid values: 'json', 'php'
5. sort (optional, defaults to 1)
   1 — Sort by oldest post first
   2 — Sort by oldest newest first
   3 — Sort by oldest best first
   4 — Sort by oldest hottest first
   
6. page (optional, defaults to 1)
   Page number, used if per_page is non-zero for pagination.
7. per_page (optional, defaults to 25)
   Passing in zero for per_page will turn off pagination and all posts will be returned.
8. flat (optional, defaults to false)
   Determine whether or not to return posts in a threaded or flat view. This will affect how posts are sorted.
9. callback (optional)
   Response type will be forced to 'json', and the response object will be passed to the provided callback method.

Response:

{
	'posts': {
		'id', (unique numeric ID for post)
		'parent_id', (unique numeric ID for parent post)
		'depth', (integer representing how many levels deep the post is indented)
		'indent', (boolean representing whether or not post is indented from previous post)
		'message',
		'date',
		'points',
		'killed', (killed or deleted posts are only returned if child posts exists for the post)
		'user',
			'id', (unique numeric ID for user or 0 for anonymous users)
			'has_avatar', (boolean representing whether user has an avatar or not)
			'display_name', (display name for user)
			'points',
			'url',
			'profile', (alphanumeric identifier for profile URL, e.g., http://disqus.com/people/<profile>/)
			'is_anonymous',
			'is_creator', (boolean flag set to true if user is the thread creator)
		}
	}
	'num_posts',
	'num_pages', (if per_page is nonzero, then this is the number of pages available)
	'page', (current requested page)
	'forum_url', (Disqus forum URL)
	'thread_id', (unique numeric identifier for thread)
	'thread_slug', (unique human-readable identifier for thread)
}			

get_num_posts

Returns the number of posts for a thread.

URL: http://disqus.com/api/v1/get_num_posts/

Parameters:

1. forum_url (required)
   Disqus forum URL
2. One of the following are required:
   thread_id — OR — thread_slug — OR — thread_url
   Used to determine which to thread to look up.
   - thread_id is a numeric unique identifier for the thread.
   - thread_slug is the human-readable unique identifier (slug)
   - thread_url is the Link attached to the Thread.
   If multiple parameters are provided, the order of precedence is: thread_id, thread_slug, thread_url.
3. response_type (optional, defaults to 'json')
   Response format. Valid values: 'json', 'php'
4. callback (optional)
   Response type will be forced to 'json', and the response object will be passed to the provided callback method.

Response:

{
	'num_posts': num_posts
}			

get_recent_posts

Currently undocumented. Please check our blog for updates.

get_recent_contributors

Currently undocumented. Please check our blog for updates.

get_user_posts

Currently undocumented. Please check our blog for updates.

get_user_profile

Currently undocumented. Please check our blog for updates.