Danbooru

Read the rules before proceeding!

help:api

Danbooru offers a REST-like API to make scripting easy. All you need is a way to GET, POST, PUT and DELETE to URLs. Responses are given in either XML or JSON format.

Testing

API calls can be tested on https://testbooru.donmai.us. Scripts should be tested there before using them on the main site.

Basics

HTTP defines four basic request methods: GET, POST, PUT and DELETE. You'll be using these methods to interact with the Danbooru API. Most API calls that change the state of the database (like creating, updating, or deleting something) require an HTTP POST, PUT or DELETE call. API calls that only retrieve data can typically be done with an HTTP GET call.

A URL is considered a resource and the HTTP methods are actions you perform on the resource. For example, GET /posts/1.json returns a JSON representation of a post. GET /posts/1.xml returns an XML representation. POST /posts/1.json would update the resource, for example changing its tags.

Some resources require parameters. For example, you can find tags that start with the letter 'a' by calling GET /tags.json?search[name_matches]=a*. This will give you a JSON listing of all tags with names starting with an a.

For POST, PUT and DELETE requests you must pass these parameters along in the body instead of the query parameters. Body parameters may be encoded in one of two ways. The usual way is with key-values pairs using "Content-Type: application/x-www-form-urlencoded":

curl -u "$login:$api_key" -X PUT "https://testbooru.donmai.us/posts/2.json" -d 'post[rating]=s&post[tag_string]=danboo'

Parameters may also be encoded as JSON using "Content-Type: application/json":

curl -u "$login:$api_key" -X PUT "https://testbooru.donmai.us/posts/2.json" -d '{ "post": { "rating": "s", "tag_string": "danboo" } }' -H "Content-Type: application/json" 

Responses

All API calls that change state will return a single element response (for XML calls). They are formatted like this:

<?xml version="1.0" encoding="UTF-8"?>
<response success="false" reason="duplicate"/>

For JSON responses, they'll look like this:

{ "success": false, "reason": "duplicate" }

While you can usually determine success or failure based on the response object, you can also figure out what happened based on the HTTP status code. In addition to the standard ones, Danbooru uses some custom status codes in the 4xx and 5xx range.

  • 200 OK: Request was successful
  • 204 No Content: Request was successful (returned by create actions)
  • 400 Bad Request: The given parameters could not be parsed
  • 401 Unauthorized: Authentication failed
  • 403 Forbidden: Access denied (see help:users for permissions information)
  • 404 Not Found: Not found
  • 410 Gone: Pagination limit (see help:users for pagination limits)
  • 420 Invalid Record: Record could not be saved
  • 422 Locked: The resource is locked and cannot be modified
  • 423 Already Exists: Resource already exists
  • 424 Invalid Parameters: The given parameters were invalid
  • 429 User Throttled: User is throttled, try again later (see help:users for API limits)
  • 500 Internal Server Error: A database timeout, or some unknown error occurred on the server
  • 502 Bad Gateway: Server cannot currently handle the request, try again later (returned during heavy load)
  • 503 Service Unavailable: Server cannot currently handle the request, try again later (returned during downbooru)

Authentication

If you can't maintain a session via a cookie, you can pass in two parameters to authenticate: "login" and "api_key". You can discover your API key by visiting your user profile. For legacy users, "password_hash" using the old salted SHA1 hashed password is also supported.

You can also authenticate via HTTP Basic Authentication using your user name and API key.

⚠️ Your password hash and API key are personal and must be kept secret. Gaining access to either one allows full access to your account. Do not publicly post your API key or distribute it in scripts.

If you are writing a user script for a browser, you do not need to embed an API key. You can rely on the user's session.

Rate Limits

As per topic #13628, API reads are not limited, but most kinds of update actions are rate-limited according to user level:

  • Basic users: 1 update/second
  • Gold users w/API key: 2 updates/second
  • Platinum/Builder/Mod w/API key: 4 updates/second

In addition, users have a burst pool where they can make several consecutive updates before being rate limited. This is again dependent on user level:

  • Basic users: 10 updates at once
  • Gold users w/API key: 30 updates at once
  • Platinum/Builder/Mod w/API key: 60 updates at once

This pool is regenerated according to the rate limiting rules mentioned above.

Queries

Common Search Parameters

All search endpoints support a common set of parameters:

  • page Returns the given page. Subject to maximum page limits (see help:users).
    You can also use b<id> and a<id> to request results before <id> or after <id>, respectively.
    E.g. to get a page of posts before post #999999, you'd make a request to /posts.json?page=b999999.
  • limit The number of results to return per page. The maximum limit is 200 for /posts.json and 1000 for everything else.
  • search[id]
  • search[created_at]
  • search[updated_at]
  • search[order]=custom Returns results in the same order as given by search[id]=3,2,1.
Parameter Parsing

Numeric search parameters support ranges:

  • 100
  • >100
  • >=100
  • <100
  • <=100
  • 100,200,300
  • 100..200 (inclusive)

Date parameters also support ranges:

  • 2012-01-01
  • >2012-01-01
  • >=2012-01-01
  • <2012-01-01
  • <=2012-01-01
  • 2012-01-01,2012-01-02
  • 2012-01-01..2013-01-01 (inclusive)

Boolean parameters accept any of the following values for true or false:

  • True: true, t, yes, y, on, 1
  • False: false, f, no, n, off, 0

Most string parameters support using asterisks (*) as wildcards. Wildcards can be escaped with \*. Literal backslashes can be escaped with \\.

Versioned Types

Type Versions

Non-versioned Types

Other Functions

List of API endpoints