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.

h1. 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":/posts/1.json returns a JSON representation of a post. GET "/posts/1.xml":/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*":/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 will be passing these parameters along in the body instead of the query parameters.

h1. Responses

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

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

For JSON responses, they'll look like this:

[quote]
{ "success": false, "reason": "duplicate" }
[/quote]

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.

* [b]200 OK[/b]: Request was successful
* [b]204 No Content[/b]: Request was successful
* [b]403 Forbidden[/b]: Access denied
* [b]404 Not Found[/b]: Not found
* [b]420 Invalid Record[/b]: Record could not be saved
* [b]421 User Throttled[/b]: User is throttled, try again later
* [b]422 Locked[/b]: The resource is locked and cannot be modified
* [b]423 Already Exists[/b]: Resource already exists
* [b]424 Invalid Parameters[/b]: The given parameters were invalid
* [b]500 Internal Server Error[/b]:  Some unknown error occurred on the server
* [b]503 Service Unavailable[/b]: Server cannot currently handle the request, try again later

h1. Authentication

If you can't maintain a session via a cookie, you can pass in two parameters to authenticate: login and api_key. For legacy users, password_hash using the old salted SHA1 hashed password is also supported. Your API key is equivalent to your bcrypted password hash, which is stored in your cookies as password_hash. You can discover your API key by visiting your user profile. Your API key is intended to be a secret so you should not publicly distribute it.

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

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.

Anonymous users can make 500 requests an hour. Basic members can make 3,000 requests an hour. Gold members can make 10,000 requests an hour. Platinum members can make 20,000 requests an hour.

h1. Queries

[expand=Posts]
h2. Listing

The base URL is GET /posts.json.

* [b]limit[/b] How many posts you want to retrieve. There is a hard limit of 100 posts per request.
* [b]page[/b] The page number.
* [b]tags[/b] The tags to search for. Any tag combination that works on the web site will work here. This includes all the meta-tags.
* [b]raw[/b] When this parameter is set the tags parameter will not be parsed for aliased tags, metatags or multiple tags, and will instead be parsed as a single literal tag.

h2. Show

The base URL is GET /posts/$id.json where $id is the post id.

h2. Create

You cannot directly create posts. You must create an upload, which is then converted into a post.

h2. Update

The base URL is PUT /posts/$id.json where $id is the post id.

* [b]post[tag_string][/b] A space delimited list of tags.
* [b]post[rating][/b] The rating for the post. Can be: s (for safe), q (for questionable), or e (for explicit).
* [b]post[source][/b] If this is a URL, Danbooru will download the file.
* [b]post[parent_id][/b] The ID of the parent post.

h2. Delete

You cannot delete posts. You can only flag them for deletion (see PostFlag resource).

h2. Revert

The base URL is PUT /posts/$id/revert.json where $id is the post id.

* [b]version_id[/b] REQUIRED The post version id to revert to.

h2. Copy notes

The base URL is PUT /posts/$id/copy_notes.json where $id is the post id.

* [b]other_post_id[/b] REQUIRED The id of the post to copy notes to.

[/expand]

[expand=Post Votes]
h2. Create

The base URL is POST /posts/$post_id/votes.json where $post_id is the post id.

* [b]score[/b] REQUIRED Can be: up, down.

[/expand]

[expand=Post Flags]
h2. Listing

The base URL is GET /post_flags.json.

* [b]search[creator_id][/b] The user id of the flag's creator.
* [b]search[creator_name][/b] The name of the flag's creator.
* [b]search[post_id][/b] The post id if the flag.

h2. Create

The base URL is POST /post_flags.json.

* [b]post_flag[post_id][/b] REQUIRED The id of the flagged post.
* [b]post_flag[reason][/b] REQUIRED The reason of the flagging.

[/expand]

[expand=Post Appeals]
h2. Listing

The base URL is GET /post_appeals.json.

* [b]search[creator_id][/b] The user id of the appeal's creator.
* [b]search[creator_name][/b] The name of the appeal's creator.
* [b]search[post_id][/b] The post id if the appeal.

h2. Create

The base URL is POST /post_appeals.json.

* [b]post_appeal[post_id][/b] REQUIRED The id of the appealed post.
* [b]post_appeal[reason][/b] REQUIRED The reason of the appeal.

[/expand]

[expand=Uploads]
h2. Listing

The base URL is GET /uploads.json.

* [b]search[uploader_id][/b] The id of the uploader.
* [b]search[uploader_name][/b] The name of the uploader.
* [b]search[source][/b] The source of the upload (exact string match).

h2. Show

The base URL is GET /uploads/$id.json where $id is the upload id.

h2. Create

The base URL is POST /uploads.json.

* [b]upload[file][/b] The file data encoded as a multipart form.
* [b]upload[source][/b] The source URL.
* [b]upload[rating][/b] REQUIRED Can be: safe, questionable, explicit.
* [b]upload[parent_id][/b] The parent post id.
* [b]upload[tag_string][/b] REQUIRED The tags.

Either the file or the source must be provided.

[/expand]

[expand=Comments]
h2. Listing

The base URL is GET /comments.json.

* [b]group_by[/b] Must be: comment
* [b]search[body_matches][/b] Body contains the given terms.
* [b]search[post_id][/b]
* [b]search[post_tags_match][/b] The comment's post's tags match the given terms. Meta-tags not supported.
* [b]search[creator_name][/b] The name of the creator (exact match)
* [b]search[creator_id][/b] The user id of the creator

h2. Create

The base URL is POST /comments.json

* [b]comment[post_id][/b] REQUIRED
* [b]comment[body][/b] REQUIRED
* [b]comment[do_not_bump_post][/b] Set to 1 if you do not want the post to be bumped to the top of the comment listing

h2. Update

The base URL is PUT /comments/$id.json where $id is the comment id.

* [b]comment[body][/b] REQUIRED
* [b]comment[do_not_bump_post][/b] Set to 1 if you do not want the post to be bumped to the top of the comment listing

h2. Show

The base URL is GET /comments/$id.json where $id is the comment id.

h2. Delete

The base URL is DELETE /comments/$id.json where $id is the comment id.

[/expand]

[expand=Dmails]
h2. Listing

The base URL is GET /dmails.json. You can only view dmails you own.

* [b]search[message_matches][/b] The message body contains the given terms.
* [b]search[to_name][/b] The recipient's name.
* [b]search[to_id][/b] The recipient's user id.
* [b]search[from_name][/b] The sender's name.
* [b]search[from_id][/b] The sender's user id.
* [b]search[read][/b] Can be: true, false

h2. Show

The base URL is GET /dmails/$id.json where $id is the dmail id. You can only view dmails you own.

h2. Create

The base URL is POST /dmails.json.

* [b]dmail[to_name][/b] The recipient's name.
* [b]dmail[title][/b] The title of the message.
* [b]dmail[body][/b] The body of the message.

h2. Delete

The base URL is DELETE /dmails/$id.json where $id is the dmail id. You can only delete dmails you own.

[/expand]

[expand=Artists]
h2. Listing

The base URL is GET /artists.json.

* [b]search[name][/b] This field has multiple uses depending on what the query starts with:
** [i]http[/i] Search for artist with this URL.
** [i]name:[/i] Search for artists with the given name as their base name..
** [i]other:[/i] Search for artists with the given name in their other names.
** [i]group:[/i] Search for artists belonging to the group with the given name.
** [i]status:banned[/i] Search for artists that are banned.
** [i]else[/i] Search for the given name in the base name and the other names.
* [b]search[id][/b] The artist id.
* [b]search[creator_name][/b]
* [b]search[creator_id][/b]
* [b]search[is_active][/b] Can be: true, false
* [b]search[is_banned][/b] Can be: true, false
* [b]search[empty_only][/b] Search for artists that have 0 posts. Can be: true
* [b]search[order][/b] Can be: name, date.

h2. Show

The base URL is GET /artists/$id.json where $id is the artist id.

h2. Create

The base URL is POST /artists.json.

* [b]artist[name][/b]
* [b]artist[other_names_comma][/b] List of alternative names for this artist, comma delimited.
* [b]artist[group_name][/b] The name of the group this artist belongs to.
* [b]artist[url_string][/b] List of URLs associated with this artist, whitespace or newline delimited.

h2. Update

The base URL is PUT /artists/$id.json where $id is the artist id.

* [b]artist[name][/b]
* [b]artist[other_names_comma][/b] List of alternative names for this artist, comma delimited.
* [b]artist[group_name][/b] The name of the group this artist belongs to.
* [b]artist[url_string][/b] List of URLs associated with this artist, whitespace or newline delimited.

h2. Delete

The base URL is DELETE /artists/$id.json where $id is the artist id.

h2. Banned

The base URL is GET /artists/banned.json. This is a shortcut for an artist listing search with name=status:banned.

h2. Revert

The base URL is PUT /artists/$id/revert.json where $id is the artist id.

* [b]version_id[/b] REQUIRED The artist version id to revert to.

[/expand]

[expand=Notes]
h2. Listing

The base URL is GET /notes.json.

* [b]search[body_matches][/b] The note's body matches the given terms.
* [b]search[post_id][/b]
* [b]search[post_tags_match][/b] The note's post's tags match the given terms. Meta-tags are not supported.
* [b]search[creator_name][/b] The creator's name. Exact match.
* [b]search[creator_id][/b] The creator's user id.

Use /notes.json?group_by=note&search[post_id]=$id to get notes from $id.

h2. Show

The base URL is GET /notes/$id.json where $id is the note id.

h2. Create

* [b]note[post_id][/b] REQUIRED
* [b]note[x][/b] REQUIRED The x coordinates of the note in pixels, with respect to the top-left corner of the image.
* [b]note[y][/b] REQUIRED The y coordinates of the note in pixels, with respect to the top-left corner of the image.
* [b]note[width][/b] REQUIRED The width of the note in pixels.
* [b]note[height][/b] REQUIRED The height of the note in pixels.
* [b]note[body][/b] REQUIRED The body of the note.

h2. Update

The base URL is PUT /notes/$id.json where $id is the note id.

* [b]note[x][/b] The x coordinates of the note in pixels, with respect to the top-left corner of the image.
* [b]note[y][/b] The y coordinates of the note in pixels, with respect to the top-left corner of the image.
* [b]note[width][/b] The width of the note in pixels.
* [b]note[height][/b] The height of the note in pixels.
* [b]note[body][/b] The body of the note.

h2. Delete

The base URL is DELETE /notes/$id.json where $id is the note id.

h2. Revert

The base URL is PUT /notes/$id/revert.json where $id is the note id.

* [b]version_id[/b] REQUIRED The note version id to revert to.

[/expand]

[expand=Users]
h2. Levels

Users have a number attribute called level representing their role. The current levels are:

* Member: 20
* Gold: 30
* Platinum: 31
* Builder: 32
* Moderator: 40
* Admin: 50

h2. Listing

The base URL is GET /users.json.

* [b]search[name][/b] Supports patterns.
* [b]search[min_level][/b] Minimum level (see section on levels).
* [b]search[max_level][/b] Maximum level (see section on levels).
* [b]search[level][/b] Current level (see section on levels).
* [b]search[id][/b] The user id.
* [b]search[order][/b] Can be: name, post_upload_count, note_count, post_update_count, date.

h2. Show

The base URL is GET /users/$id.json where $id is the user id.

[/expand]

[expand=Post Versions]
h2. Listing

The base URL is GET /post_versions.json.

* [b]search[updater_name][/b]
* [b]search[updater_id][/b]
* [b]search[post_id][/b]
* [b]search[start_id][/b]

[/expand]

[expand=Note Versions]
h2. Listing

The base URL is GET /note_versions.json.

* [b]search[updater_id][/b]
* [b]search[post_id][/b]
* [b]search[note_id][/b]

[/expand]

[expand=Artist Versions]
h2. Listing

The base URL is GET /artist_versions.json.

* [b]search[name][/b]
* [b]search[updater_id][/b]
* [b]search[artist_id][/b]
* [b]search[is_active][/b] Can be: true, false
* [b]search[is_banned][/b] Can be: true, false
* [b]search[order][/b] Can be: name, date

[/expand]

[expand=Pools]
h2. Listing

The base URL is GET /pools.json.

* [b]search[name_matches][/b]
* [b]search[description_matches][/b]
* [b]search[creator_name][/b]
* [b]search[creator_id][/b]
* [b]search[is_active][/b] Can be: true, false
* [b]search[order][/b] Can be: name, created_at, post_count, date
* [b]search[category][/b] Can be: series, collection

h2. Show

The base URL is GET /pools/$id.json where $id is the pool id.

h2. Create

The base URL is POST /pools.json.

* [b]pool[name][/b] REQUIRED
* [b]pool[description][/b] REQUIRED
* [b]pool[category][/b] Can be: series, collection

h2. Update

The base URL is PUT /pools/$id.json where $id is the pool id.

* [b]pool[name][/b]
* [b]pool[description][/b]
* [b]pool[post_ids][/b] List of space delimited post ids.
* [b]pool[is_active][/b] Can be: 1, 0
* [b]pool[category][/b] Can be: series, collection

h2. Delete

The base URL is DELETE /pools/$id.json where $id is the pool id.

h2. Undelete

The base URL is POST /pools/$id/undelete.json where $id is the pool id.

h2. Revert

The base URL is PUT /pools/$id/revert.json where $id is the pool id.

* [b]version_id[/b] REQUIRED

[/expand]

[expand=Pool Versions]
h2. Listing

The base URL is GET /pool_versions.json.

* [b]search[updater_id][/b]
* [b]search[updater_name][/b]
* [b]search[pool_id][/b]

[/expand]

[expand=Tags]
h2. Listing

The base URL is GET /tags.json.

* [b]search[name_matches][/b]
* [b]search[category][/b] Can be: 0, 1, 3, 4 (general, artist, copyright, character respectively)
* [b]search[hide_empty][/b] Can be: yes, no. Excludes tags with 0 posts when "yes".
* [b]search[order][/b] Can be: name, date, count
* [b]search[has_wiki][/b] Can be: yes, no
* [b]search[name][/b] Allows searching for multiple tags with exact given names, separated by commas. e.g. search[name]=touhou,original,k-on! would return the three listed tags.

[/expand]

[expand=Tag Aliases]
h2. Listing

The base URL is GET /tag_aliases.json.

* [b]search[name_matches][/b] Match antecedent or consequent name.
* [b]search[antecedent_name][/b] Match antecedent name (exact match).
* [b]search[id][/b] The tag alias id.

[/expand]

[expand=Tag Implications]
h2. Listing

The base URL is GET /tag_implications.json.

* [b]search[name_matches][/b] Match antecedent or consequent name.
* [b]search[antecedent_name][/b] Match antecedent name (exact match).
* [b]search[id][/b] The tag implication id.

[/expand]

[expand=Wiki Pages]
h2. Listing

The base URL is GET /wiki_pages.json.

* [b]search[title][/b]
* [b]search[creator_id][/b]
* [b]search[body_matches][/b]
* [b]search[other_names_match][/b]
* [b]search[creator_name][/b]
* [b]search[order][/b] Can be: date, title.

h2. Show

The base URL is GET /wiki_pages/$id.json where $id is the wiki page id.

h2. Create

The base URL is POST /wiki_pages.json.

* [b]wiki_page[title][/b] REQUIRED
* [b]wiki_page[body][/b] REQUIRED
* [b]wiki_page[other_names][/b]

h2. Update

The base URL is PUT /wiki_pages/$id.json where $id is the wiki page id.

* [b]wiki_page[title][/b]
* [b]wiki_page[body][/b]
* [b]wiki_page[other_names][/b]

h2. Revert

The base URL is PUT /wiki_pages/$id/revert.json where $id is the wiki page id.

* [b]version_id[/b] REQUIRED

[/expand]

[expand=Related Tags]
h2. Show

The base URL is GET /related_tag.json.

* [b]query[/b] REQUIRED The tag to find the related tags for.
* [b]category[/b] If specified, show only tags of a specific category. Can be:
** [i]General[/i] 0
** [i]Artist[/i] 1
** [i]Copyright[/i] 3
** [i]Character[/i] 4

[/expand]

[expand=Forum Topics]
h2. Listing

The base URL is GET /forum_topics.json.

* [b]search[title_matches][/b] Search body for the given terms.
* [b]search[title][/b] Exact title match.
* [b]search[category_id][/b] Can be: 0, 1, 2 (General, Tags, Bugs & Features respectively)

h2. Show

The base URL is GET /forum_topics/$id.json where $id is the forum topic id.

h2. Create

The base URL is POST /forum_topics.json.

* [b]forum_topic[title][/b]
* [b]forum_topic[original_post_attributes][body][/b] Message of the initial post.
* [b]forum_topic[category_id][/b]

h2. Update

The base URL is PUT /forum_topics/$id.json where $id is the forum topic id.

* [b]forum_topic[title][/b]
* [b]forum_topic[category_id][/b]

h2. Delete

The base URL is DELETE /forum_topics/$id.json where $id is the forum topic id.

h2. Undelete

The base URL is POST /forum_topics/$id/undelete.json where $id is the forum topic id.

[/expand]

[expand=Forum Posts]
h2. Listing

The base URL is GET /forum_posts.json.

* [b]search[creator_id][/b]
* [b]search[creator_name][/b]
* [b]search[topic_id][/b]
* [b]search[topic_title_matches][/b]
* [b]search[topic_category_id][/b] Can be: 0, 1, 2 (General, Tags, Bugs & Features respectively)
* [b]search[body_matches][/b]

h2. Create

The base URL is POST /forum_posts.json.

* [b]forum_post[body][/b]

h2. Update

The base URL is PUT /forum_posts/$id.json where $id is the forum post id.

* [b]forum_post[body][/b]

h2. Delete

The base URL is DELETE /forum_posts/$id.json where $id is the forum post id.

h2. Undelete

The base URL is POST /forum_posts/$id/undelete.json where $id is the forum post id.

[/expand]

[expand=Artist Commentary]
h2. Listing

The base URL is GET /artist_commentaries.json.

* [b]search[text_matches][/b]
* [b]search[post_tags_match][/b] The commentary's post's tags match the given terms. Meta-tags not supported.
* [b]search[original_present][/b] Can be: yes, no
* [b]search[translated_present][/b] Can be: yes, no

h2. Create or Update

The base URL is POST /artist_commentaries/create_or_update.json

* [b]artist_commentary[post_id][/b] REQUIRED
* [b]artist_commentary[original_title][/b]
* [b]artist_commentary[original_description][/b]
* [b]artist_commentary[translated_title][/b]
* [b]artist_commentary[translated_description][/b]

h2. Revert

The base URL is PUT /artist_commentaries/$id/revert.json where $id is the post id (not the artist commentary id).

* [b]version_id[/b] REQUIRED The artist commentary version id to revert to.

[/expand]

[expand=Artist Commentary Versions]
h2. Listing

The base URL is GET /artist_commentary_versions.json.

* [b]search[updater_id][/b]
* [b]search[post_id][/b]

[/expand]
