API Usage

This is the documentation for the v1.1 read-only Stack Exchange API. If you have additional questions, or believe you have encountered a bug, don't hesitate to post a question on Stack Apps.

If your application is in a runnable state (even a beta one), Stack Apps is also the place to list it.

General

All API responses are JSON, we do support JSONP with the jsonp query parameter.

Additionally, all API responses are GZIP'd. The Content-Encoding header is always set, but some proxies will strip this out. The proper way to decode API responses can be found here.

API usage is throttled by IP address. Each IP can make a certain number of requests per-day. Without an API key, this limit is quite low.
Note that API keys are not secret, nor do they "stack." A single IP running a dozen registered applications can make the same number of requests per day as an IP running a single registered application.

API responses are heavily cached. Polling for changes should be done sparingly in any case, and polling at a rate faster than once a minute (for semantically identical requests) is considered abusive.

Application and library developers should be aware that the returned values from the API are not of any particular size, regardless of any limits that may be placed on the Stack Exchange network sites at the moment. Furthermore, the API only makes a best effort attempt to fill all applicable fields on returned objects; an application should be able to handle partial returns sensibly.

Possible values for various "enumeration fields" returned by the API can be found listed here.

Methods

Many API methods are vectorized. That is to say, they will accept multiple values within a single parameter on a request.
If a parameter on this page is in the url path and plural you can pass multiple values separated by semi-colons. The documentation for specific methods will call out vectorized parameters further.

Answers

Badges

  • /badges – Get all badges on the site, in alphabetical order.
  • /badges/{ids} – Get all users who have been awarded the badges identified by ids.
  • /badges/name – Get all non-tagged-based badges in alphabetical order.
  • /badges/tags – Get all tagged-based badges in alphabetical order.

Comments

Errors

  • /errors/{id} – Simulate an API error for testing purposes.

Privileges

  • /privileges – Get all the privileges available on the site. 1.1

Questions

Revisions

Search

  • /search – Search the site for questions meeting certain criteria.
  • /similar – Search the site based on similarity to a title. 1.1

Stats

  • /stats – Get a set of statistics for the entire site.

Tags

Users

Stack Auth Methods

Stack Auth serves as a central hub for a variety of network wide functions. Accordingly, functions for network wide account lookup and site discovery reside there.

Sites

  • /sites – Get all the sites in the Stack Exchange network.1.1

Users

Note that 1.0 versions of the Stack Auth methods exist. These new methods are trying out some new ideas with regards to the form of API returns on a small scale before the next major API revision.