DISQUS

Introduction

The Disqus API aims to give software developers constructive access to our data. In this early version, the goal is to be just sufficient to write a custom Disqus integration for your site. More methods will appear quickly. The direction (and speed) of API progress will be entirely determined by developer demand, so if you have any requests or feedback, write to team@disqus.com and we will try to accomodate your request. Although the API is just getting started, the methods below won't change barring exceptional circumstances.

API Keys

There are two different kinds of API 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, below.

Request and Response Format

Request format: This is an API over HTTP. All methods are GET requests unless otherwise specified. Methods are available at http://disqus.com/api/(method_name)/. If a method requires your User Key, it should be passed in a parameter called "user_api_key"; a Forum Key should be passed in "forum_api_key".

Response format: All responses are JSON objects with three fields:

1. succeeded: Indicates whether the call completed successfully or encountered an error.
2. code: "ok" if succeeded, otherwise an short description of the error that occurred.
3. 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.

API Methods

get_forum_list:

• Key: User Key
• Arguments: None.
• Result: A list of objects representing all forums the user owns. The user is determined by the API key. See "Object Formats" header below for details on forum objects.

get_forum_api_key:

• Key: User Key
• Arguments: "forum_id", the unique id of the forum.
• Result: A string which is the Forum Key for the given forum.

get_thread_list:

• Key: Forum Key
• Arguments: None.
• Result: A list of objects representing all threads belonging to the given forum. See "Object Formats" for details on thread objects.

get_num_posts:

• Key: Forum Key
• Arguments: "thread_ids", a comma-separated list of thread IDs belonging to the given forum.
• Result: An object mapping each thread_id to a list of two numbers. The first number is the number of visible comments on on the thread; this would be useful for showing users of the site (e.g., "5 Comments"). The second number is the total number of comments on the thread. These numbers are different because some forums require moderator approval, some messages are flagged as spam, etc.

get_thread_posts:

• Key: Forum Key
• Arguments: "thread_id", the ID of a thread belonging to the given forum.
• Result: A list of objects representing all posts belonging to the given forum. See "Object Formats" for details on post objects.

thread_by_identifier:

• Key: Forum Key
• Method: POST
• Arguments: "title", the title of the thread to possibly be created; and "identifier", a string of your choosing (see Action).
• Action: Create or retrieve a thread by an arbitrary identifying string of your choice. For example, you could use your local database's ID for the thread. This method allows you to decouple thread identifiers from the URLs on which they might be appear. (Disqus would normally use a thread's URL to identify it, which is problematic when URLs do not uniquely identify a resource.) If no thread yet exists for the given identifier (paired with the forum), one will be created.
• Result: An object with two keys: "thread", which is the thread object corresponding to the identifier; and "created", which indicates whether the thread was created as a result of this method call.

Posting a Comment

The above methods allow you to create threads and display their posts. How do you let your users add a comment? For now, the answer is to embed a Disqus-reply IFRAME via the following javascript file. We are still determining the best way to integrate our login with third-party sites.

Object Formats

API responses contain JSON-formatted representations of Disqus objects. The fields the objects contain are described below. If you see any fields in the live data that are not documented below, you shouldn't rely on them.

Forum object

• id field: a unique alphanumeric string identifying this Forum object.
• shortname: the unique string used in disqus.com URLs relating to this forum. For example, if the shortname is "bmb", the forum's community page is at http://bmb.disqus.com/.
• name: a string for displaying the forum's full title, like "The Eyeball Kid's Blog".

Thread object

• id: a unique alphanumeric string identifying this Thread object.
• forum: the id for the forum this thread belongs to.
• slug: the per-forum-unique string used for identifying this thread in disqus.com URLs relating to this thread.
• title: the title of the thread, like "A picture I took".
• created_at: the UTC date this thread was created, in the format %Y-%m-%dT%H:%M.
• allow_comments: whether this thread is open to new comments.

Post object

• id: a unique alphanumeric string identifying this Post object.
• forum: the id for the forum this post belongs to.
• thread: the id for the thread this post belongs to.
• created_at: the UTC date this post was created, in the format %Y-%m-%dT%H:%M.
• message: the contents of the post, such as "First post".
• shown: whether the post is currently visible or not.
• is_anonymous: whether the comment was left anonymously, as opposed to a registered Disqus account.
• anonymous_author: present only when is_anonymous is true. An object containing these fields:
  • name: the display name of the commenter
  • url: their optionally provided homepage
  • email_hash: md5 of the author's email address
• author: present only when is_anonymous is false. An object containing these fields:
  • id: the unique id of the commenter's Disqus account
  • username: the author's username
  • url: their optionally provided homepage
  • email_hash: md5 of the author's email address
  • has_avatar: whether the user has an avatar on disqus.com

FAQ

Are there limits on API usage? How many requests can I make? We don't have a formal policy about this yet. If you're going to be making a high volume of requests, just let us know ahead of time and make sure it's ok.

What about accessing the data of a forum I don't own? We want to provide this kind of access, but in a way that does not infringe on the rights of the forum owner. This is still in progress. Accessing your own data was the first priority in developing the API.

What if my question is not Frequently Asked? Don't be shy. Write to team@disqus.com.