DISQUS API 1.1 Documentation

(VERSION: by Anton Kovaloyvok (DISQUS) – Mar 9 2010 – edited Prabir Shrestha – www.prabir.me)

Table of Contents

Introduction

The Disqus API enables developers to interact with the Disqus data from their programs. Our first practical goal is to offer sufficient access for someone to write a custom Disqus plugin or a third-party application.

If you have any requests, write to help@disqus.com and we will try to accommodate your request. You can also post any questions here, in the DISQUS Developers mailing list.

Requests and Data Formats

Disqus API works over HTTP. Each method is provided at the address http://disqus.com/api/{method_name}. By default, requests are HTTP GET requests. All arguments are passed as GET parameters if the method is a GET request, and POST parameters if POST.

 

There are three types of Disqus objects that this API provides access to: forums, threads, and posts. A post is any comment written by a Disqus user. Each post belongs to a thread, which represents a particular topic of conversation. Each thread belongs to a forum. A forum represents a website that is using Disqus. For example, your blog might constitute a single forum, and each blog post would have its own thread.

 

For each request you should specify which version of the API you want to use (default is 1.0). To do it, include api_version parameter in each request you make to the API. For current version use '1.1' as a value.

 

 

Authentication

 

When a third-party application wants to use the Disqus API it will need API keys. There are three different kinds of keys. First is the user key. Every Disqus account has a user key; it is used to perform actions associated with that account. When you are logged in, you can get yours here. Keep this key private.

 

The second kind of key is the forum key. Every Disqus forum has a forum key. It can be shared among trusted moderators of a forum, and is used to perform actions associated with that forum. The creator of a forum can get the forum's key through the API (see below).

 

The last one is a partner key. Unless you need something extraordinary, you do not need it.

Response Formats

All responses are JSON objects with three fields:

·         succeeded: Indicates whether the call completed successfully or encountered an error.

·         code: 'ok' if succeeded, otherwise an short description of the error that occurred.

·         message: The body of the response, which will depend on the method being used. In case of error, contains a longer description of the error that occurred.

Here is the example of a successful request to our API:

$ curl -0 -L "http://disqus.com/api/get_forum_list?user_api_key=API_KEY_HERE&api_version=1.1"

{

  "message": [

    {

      "created_at": "2007-07-31 17:44:00",

      "shortname": "disqus",

      "description":

      "The official Disqus forum. [...]",

      "id": "NN", "name": "DISQUS Blog and Forum"
    },
    {
      "created_at": "2008-09-10 14:37:31.744838",
      "shortname": "antonkovalyov",
      "description": "",
      "id": "NN",
      "name": "Anton Kovalyov"
    }
  ],
  "code": "ok",
  "succeeded": true
}

 

Methods

get_user_name — Validate API key and get username

Method: POST

Required arguments:

This method validates API key and returns username that is associated with it.

get_forum_api_key — Get a forum API key for a specific forum

Method: GET

Required arguments:

Returns a string which is forum API key for a given forum.

 

get_forum_list — Get a list of websites that user owns or moderates

 

Method: GET

 

Required arguments:

get_forum_posts — Get a list of comments on a website

Method: GET

 

Required arguments:

Optional arguments:

 

Returns posts from a forum specified by id.

 

Both filter and exclude are multivalue arguments with coma as a divider. That makes is possible to use combined requests. For example, if you want to get all deleted spam messages, your filter argument should contain 'spam,killed' string.

get_num_posts — Count a number of comments in articles

Method: GET

 

Required arguments:

This API method returns a hash of threads with their id as a key and number of posts in them as a value.

 

get_categories_list — Get a list of categories on a website

Method: GET

Required arguments:

Returns a list of categories that were created for a website (forum) provided. Returned data will contain category id, title, forum_id and boolean flag is_default.

get_thread_list — Get a list of threads on a website

 

Method: GET

 

Required arguments:

Optional arguments:

get_updated_threads — Get a list of threads with new comments

 

Method: GET

 

Required arguments:

get_thread_posts — Get a list of comments in a thread

Method: GET

Required arguments:

Optional arguments:

Both filter and exclude are multivalue arguments with coma as a divider. That makes is possible to use combined requests. For example, if you want to get all deleted spam messages, your filter argument should contain 'spam,killed' string. Note that values are joined by AND statement so 'spam,new' will return all messages that are new and marked as spam. It will not return messages that are new and not spam or that are spam but not new (i.e. has already been moderated).

thread_by_identifier — Get or create thread by identifier

Method: POST

Required arguments:

Optional arguments:

This method tries to find a thread by its identifier and title. If there is no such thread, the method creates it. In either case, the output value is a thread object.

get_thread_by_url — Get thread by URL

Method: GET

 

Required arguments:

Optional arguments:

Finds a thread by its URL. Output value is a thread object.

update_thread — Update thread

Method: POST

Required arguments:

Optional arguments:

Updates thread, specified by id and forum API key, with values described in the optional arguments above.

create_post — Create a new post (i.e. add a new comment)

Method: POST

Required arguments:

Optional arguments:

Creates a comment to the thread specified by id.

moderate_post — Delete a comment or mark it as spam (or not spam)

Method: POST

 

Required arguments:

Moderates post and returns modified version