API Resources

Request and Response Formats

The Disqus API works over the HTTP protocol. It supports both server-side (secret key) methods, as well as a public facing JavaScript API using your public key and HTTP referrer checks. In general, read requests are made with GET and write requests are made with POST.

Constructing Requests

Requests are made of three components:

  • API version
  • Resource path
  • Output type

To construct a proper request, you will need to format the URI as follows:

https://disqus.com/api/{version}/{resource}.{output_type}

An example request, to fetch a list of posts on a forum might be:

https://disqus.com/api/3.0/forums/listPosts.json?forum=disqus

Note: We recommend using SSL for all requests to the API.

By default, requests are HTTP GET requests. However, many methods will require you to send POST data. Typically, we try to follow the standard of all read requests use GET, and write requests use POST.

In addition to the required parameters for each individual method, you will also need to send your API key, this is done differently depending on how you access the resource.

If you are using the public-facing JavaScript API, you will need to send api_key with your public API key value. You will need to also ensure that you have added the domain you're accessing the API from to your list of domains for that application.

If you are using the server-side API, you will need to send api_secret with your secret API key value.

API Version

For each request you should specify which version of the API you want to use. Currently, the default, and the only version available, is 3.0.

Resource Path

The resource path is made available to you in further documentation.

Data Formats

Disqus only supports one data format currently, JSON. However, we do also support JSONP response types, which are just a callback function wrapping the JSON output. Callbacks are only valid in GET requests.

$ curl -0 -L "https://disqus.com/api/3.0/trends/listThreads.json?api_key=API_PUBLIC_KEY_HERE&callback=foo"
foo({
  "code": 0,
  "response": [
    {
      "thread": {
        "forum": {
          "id": "cucirca",
          "name": "Tv Shows",
          "founder": 996907,
          "favicon": {
            "permalink": "https://disqus.com/api/forums/favicons/cucirca.jpg",
            "cache": "https://a.disquscdn.com/uploads/forums/20/8466/favicon.png"
          }
        },
        "author": 996907,
        "title": "Watch True Blood Online",
        "link": "http://www.cucirca.com/2009/05/27/watch-true-blood-online/",
        "closed": false,
        "id": 40385200,
        "createdAt": "2009-10-19T04:51:26"
      },
      "comments": 14605,
      "score": "2.9408284023668639",
      "link": "http://www.cucirca.com/2009/05/27/watch-true-blood-online/",
      "likes": 62,
      "commentLikes": 9884
    }
  ]
})

Parameters

Parameters have several considerations to be made within the API.

The first are multi value parameters. This simply means that the resource allows you to send multiple values for this single parameter. This can be done in two ways:

  1. param=foo&param=bar (preferred)
  2. param[]=foo&param[]=bar

The second consideration are query types. Certain parameters allow more complex lookups by specifying a suffix on the parameter. For example, the user parameter typically allows you to look up a user by username, as well as by ID. To do this, you simply suffix the lookup key with :username.

  • user:username=foobar
  • user=13

Responses

The response of your request will contain several key things:

  • HTTP status code
  • API status code
  • API response message

Let's take an example request:

$ curl -0 -L "https://disqus.com/api/3.0/trends/listThreads.json?api_key=API_PUBLIC_KEY_HERE"
{
  "code": 0,
  "response": [
    {
      "thread": {
        "forum": {
          "id": "cucirca",
          "name": "Tv Shows",
          "founder": 996907,
          "favicon": {
            "permalink": "https://disqus.com/api/forums/favicons/cucirca.jpg",
            "cache": "https://a.disquscdn.com/uploads/forums/20/8466/favicon.png"
          }
        },
        "author": 996907,
        "title": "Watch True Blood Online",
        "link": "http://www.cucirca.com/2009/05/27/watch-true-blood-online/",
        "closed": false,
        "id": 40385200,
        "createdAt": "2009-10-19T04:51:26"
      },
      "comments": 14605,
      "score": "2.9408284023668639",
      "link": "http://www.cucirca.com/2009/05/27/watch-true-blood-online/",
      "likes": 62,
      "commentLikes": 9884
    }
  ]
}

Data Availability

Some response data, particularly personally-identifiable information, is available only in certain situations. OAuth is always required.