DISQUS

Introduction

The Disqus API aims to give software developers constructive access to our data. Our first practical goal is to offer sufficient access for someone to write a custom Disqus plugin for their site. We also aim to allow user-developed comment import and export tools. 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 (see below).

Request and Response Format

Request format: This is an API over HTTP. Each method is provided at the URL 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". All arguments are passed as GET parameters if the method is a GET request, and as POST parameters if the method requires POST. Methods are GET requests unless otherwise specified.

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.

Data Model

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.

API Methods

create_post:

• Key: Forum Key
• Method: POST
• Arguments: Required: "thread_id", the thread to post to; "message", the content of the post; "author_name", the post creator's name; and "author_email", their email address. Optional: "parent_post", the id of the parent post; "created_at", the UTC date this post was created, in the format %Y-%m-%dT%H:%M (the current time will be used by default); "author_url", the author's homepage; and "ip_address", their IP address.
• Action: Creates a new post on the thread. Does not check against spam filters or ban list. This is intended to allow automated importing of comments.
• Result: The post object just created. See "Object Formats" header below for details on post objects.

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_by_url:

• Key: Forum Key
• Arguments: "url", the URL to check for an associated thread.
• Result: A thread object if one was found, otherwise null. Only finds threads associated with the given forum. Note that there is no one-to-one mapping between threads and URLs: a thread will only have an associated URL if it was automatically created by Disqus javascript embedded on that page. Therefore, we recommend using thread_by_identifier whenever possible, and this method is provided mainly for handling comments from before your forum was using the API.

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. If created, it will have the specified title.

update_thread:

• Key: Forum Key
• Method: POST
• Arguments: Required: "thread_id", the ID of a thread belonging to the given forum. Optional: any of "title", "slug", "url", and "allow_comments".
• Action: Sets the provided values on the thread object. See Object Formats for field meanings.
• Result: An empty success message.

Posting a Comment

The above methods allow you to create threads and display their comments. To let your users add a comment, you can embed a Disqus-reply IFRAME by including following Javascript file.

• Base URL: http://disqus.com/api/reply.js
• GET arguments (required): "forum_shortname", and one of "thread_id" or "thread_identifier" to specify the thread being commented on.

You will need to create an HTML element in your page (probably a div) with the id "dsq-reply". This element should appear before the Javascript file is included. When the Javascript is loaded, the contents of the element will be replaced with the Disqus comment box. Users can leave a comment on the thread, and login or register if they are not authenticated. Note that this method does not currently support Seesmic video replies.

The embed also provides a function that you can use to allow replies to particular posts on the thread. Call "dsq_replyToPost" with the id of the post you want to reply to. This will create a Disqus reply iframe, similar to above, in an element with the id "dsq-reply-postid. For example, you could create a "reply" next to each comment in the thread which calls this function onclick. To cancel the reply, call "dsq_cancelReplyToPost", again with the post id as the argument.

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. Composed of underscore-separated alphanumeric strings.
• title: the title of the thread.
• 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.
• url: the URL this thread is on, if known.
• identifier: the user-provided identifier for this thread, as in thread_by_identifier above (if available)

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".
• parent_post: the id of the parent post, if any
• 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
  • display_name: the author's full name, if provided
  • 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? Accessing your own data is our first priority in developing the API. We want to provide this kind of access in a way that does not infringe on the rights of the forum owner. This is still in progress.

What if my question is not Frequently Asked? Write to team@disqus.com.