Help: API v1.13.0

Basics

HTTP defines two request methods: GET and POST. You'll be using these two 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 call. API calls that only retrieve data can typically be done with an HTTP GET call.

In the Danbooru API, a URL is analogous to a function name. You pass in the function parameters as a query string. Here's an extremely simple example: /post/index.xml?limit=1.

The post part indicates the controller we're working with. In this case it's posts. index describes the action. Here we're retrieving a list of posts. Finally, the xml part describes what format we want the response in. You can specify .xml for XML responses, .json for JSON responses, and nothing at all for HTML responses.

Responses

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

For JSON responses, they'll look like this:

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.

JSON Responses

While you will probably want to work with XML in the majority of cases, if you're writing something in Javascript then the JSON responses may be preferable. They are much faster to parse and there's less code to write to get your data structure:

Logging In

Some actions may require you to log in. For any action you can always specify two parameters to identify yourself:

• login Your login name.
• password_hash Your SHA1 hashed password. Simply hashing your plain password will NOT work since Danbooru salts its passwords. The actual string that is hashed is "--your-password--".

Please be aware of the security risks involved in sending your password through an unencrypted channel. Although your password will be hashed, it is still theoretically possible for someone to steal your account by creating a fake cookie based on your hashed password.

List

The base URL is /post/index.xml.

• limit How many posts you want to retrieve. There is a hard limit of 100 posts per request.
• page The page number.
• tags The tags to search for. Any tag combination that works on the web site will work here. This includes all the meta-tags.

Create

The base URL is /post/create.xml. There are only two mandatory fields: you need to supply the tags, and you need to supply the file, either through a multipart form or through a source URL.

• post[tags] A space delimited list of tags.
• post[file] The file data encoded as a multipart form.
• post[rating] The rating for the post. Can be: safe, questionable, or explicit.
• post[source] If this is a URL, Danbooru will download the file.
• post[is_rating_locked] Set to true to prevent others from changing the rating.
• post[is_note_locked] Set to true to prevent others from adding notes.
• post[parent_id] The ID of the parent post.
• md5 Supply an MD5 if you want Danbooru to verify the file after uploading. If the MD5 doesn't match, the post is destroyed.

If the call fails, the following response reasons are possible:

• MD5 mismatch This means you supplied an MD5 parameter and what Danbooru got doesn't match. Try uploading the file again.
• duplicate This post already exists in Danbooru (based on the MD5 hash). An additional attribute called location will be set, pointing to the (relative) URL of the original post.
• other Any other error will have its error message printed.

If the post upload succeeded, you'll get an attribute called location in the response pointing to the relative URL of your newly uploaded post.

Update

The base URL is /post/update.xml. Only the id parameter is required. Leave the other parameters blank if you don't want to change them.

• id The id number of the post to update.
• post[tags] A space delimited list of tags.
• post[file] The file data encoded as a multipart form.
• post[rating] The rating for the post. Can be: safe, questionable, or explicit.
• post[source] If this is a URL, Danbooru will download the file.
• post[is_rating_locked] Set to true to prevent others from changing the rating.
• post[is_note_locked] Set to true to prevent others from adding notes.
• post[parent_id] The ID of the parent post.

Destroy

You must be logged in to use this action. You must also be the user who uploaded the post (or you must be a moderator).

• id The id number of the post to delete.

Revert Tags

This action reverts a post to a previous set of tags. The base URL is /post/revert_tags.xml.

• id The post id number to update.
• history_id The id number of the tag history.

Vote

This action lets you vote for a post. You can only vote once per post per IP address. The base URL is /post/vote.xml.

• id The post id number to update.
• score Set to 1 to vote up and -1 to vote down. All other values will be ignored.

If the call did not succeed, the following reasons are possible:

• already voted You have already voted for this post.
• invalid score You have supplied an invalid score.

List

The base URL is /tag/index.xml.

• limit How many tags to retrieve. Setting this to 0 will return every tag.
• page The page number.
• order Can be date, count, or name.
• id The id number of the tag.
• after_id Return all tags that have an id number greater than this.
• name The exact name of the tag.
• name_pattern Search for any tag that has this parameter in its name.

Update

The base URL is /tag/update.xml.

• name The name of the tag to update.
• tag[tag_type] The tag type. General: 0, artist: 1, copyright: 3, character: 4.
• tag[is_ambiguous] Whether or not this tag is ambiguous. Use 1 for true and 0 for false.

Related

The base URL is /tag/related.xml.

• tags The tag names to query.
• type Restrict results to this tag type (can be general, artist, copyright, or character).

List

The base URL is /artist/index.xml.

• name The name (or a fragment of the name) of the artist.
• order Can be date or name.
• page The page number.

Create

The base URL is /artist/create.xml.

• artist[name] The artist's name.
• artist[urls] A list of URLs associated with the artist, whitespace delimited.
• artist[alias] The artist that this artist is an alias for. Simply enter the alias artist's name.
• artist[group] The group or cicle that this artist is a member of. Simply enter the group's name.

Update

The base URL is /artist/update.xml. Only the id parameter is required. The other parameters are optional.

• id The id of thr artist to update.
• artist[name] The artist's name.
• artist[urls] A list of URLs associated with the artist, whitespace delimited.
• artist[alias] The artist that this artist is an alias for. Simply enter the alias artist's name.
• artist[group] The group or cicle that this artist is a member of. Simply enter the group's name.

Destroy

The base URL is /artist/destroy.xml. You must be logged in to delete artists.

• id The id of the artist to destroy.

Show

The base URL is /comment/show.xml. This retrieves a single comment.

• id The id number of the comment to retrieve.

Create

The base URL is /comment/create.xml.

• comment[anonymous] Set to 1 if you want to post this comment anonymously.
• comment[post_id] The post id number to which you are responding.
• comment[body] The body of the comment.

Destroy

The base url is /comment/destroy.xml. You must be logged in to use this action. You must also be the owner of the comment, or you must be a moderator.

• id The id number of the comment to delete.

List

The base URL is /wiki/index.xml. This retrieves a list of every wiki page.

• order How you want the pages ordered. Can be: title, date.
• limit The number of pages to retrieve.
• page The page number.
• query A word or phrase to search for.

Create

The base URL is /wiki/create.xml.

• wiki_page[title] The title of the wiki page.
• wiki_page[body] The body of the wiki page.

Update

The base URL is /wiki/update.xml. Potential error reasons: "Page is locked"

• title The title of the wiki page to update.
• wiki_page[title] The new title of the wiki page.
• wiki_page[body] The new body of the wiki page.

Show

The base URL is /wiki/show.xml. Potential error reasons: "artist type"

• title The title of the wiki page to retrieve.
• version The version of the page to retrieve.

Destroy

The base URL is /wiki/destroy.xml. You must be logged in as a moderator to use this action.

• title The title of the page to delete.

Lock

The base URL is /wiki/lock.xml. You must be logged in as a moderator to use this action.

• title The title of the page to lock.

Unlock

The base URL is /wiki/unlock.xml. You must be logged in as a moderator to use this action.

• title The title of the page to unlock.

Revert

The base URL is /wiki/revert.xml. Potential error reasons: "Page is locked"

• title The title of the wiki page to update.
• version The version to revert to.

History

The base URL is /wiki/history.xml.

• title The title of the wiki page to retrieve versions for.

List

The base URL is /note/index.xml.

• post_id The post id number to retrieve notes for.

Search

The base URL is /note/search.xml.

• query A word or phrase to search for.

History

The base URL is /note/history.xml. You can either specify id, post_id, or nothing. Specifying nothing will give you a list of every note verison.

• limit How many versions to retrieve.
• page The offset.
• post_id The post id number to retrieve note versions for.
• id The note id number to retrieve versions for.

Revert

The base URL is /note/revert.xml. Potential error reasons: "Post is locked"

• id The note id to update.
• version The version to revert to.

Create/Update

The base URL is /note/update.xml. Notes differ from the other controllers in that the interface for creation and updates is the same. If you supply an id parameter, then Danbooru will assume you're updating an existing note. Otherwise, it will create a new note. Potential error reasons: "Post is locked"

• id If you are updating a note, this is the note id number to update.
• note[post_id] The post id number this note belongs to.
• note[x] The x coordinate of the note.
• note[y] The y coordinate of the note.
• note[width] The width of the note.
• note[height] The height of the note.
• note[is_active] Whether or not the note is visible. Set to 1 for active, 0 for inactive.
• note[body] The note message.

Search

The base URL is /user/index.xml. If you don't specify any parameters you'll get a listing of all users.

• id The id number of the user.
• name The name of the user.

List

The base URL is /forum/index.xml. If you don't specify any parameters you'll get a list of all the parent topics.

• parent_id The parent ID number. You'll return all the responses to that forum post.

List Pools

The base URL is /pool/index.xml. If you don't specify any parameters you'll get a list of all pools.

• query The title.
• page The page.

List Posts

The base URL is /pool/show.xml. If you don't specify any parameters you'll get a list of all pools.

• id The pool id number.
• page The page.

Update

The base URL is /pool/update.xml.

• id The pool id number.
• pool[name] The name.
• pool[is_public] 1 or 0, whether or not the pool is public.
• pool[description] A description of the pool.

Create

The base URL is /pool/create.xml.

• pool[name] The name.
• pool[is_public] 1 or 0, whether or not the pool is public.
• pool[description] A description of the pool.

Destroy

The base URL is /pool/destroy.xml.

• id The pool id number.

Add Post

The base URL is /pool/add_post.xml. Potential error reasons: "Post already exists", "access denied"

• pool_id The pool to add the post to.
• post_id The post to add.

Remove Post

The base URL is /pool/remove_post.xml. Potential error reasons: "access denied"

• pool_id The pool to remove the post from.
• post_id The post to remove.

1.15.0

• Added documentation for pools

1.13.0

• Changed interface for artists to use new URL system
• JSON requests now end in a .json suffix
• Renamed some error reason messages
• Removed comment/index from API
• Removed url and md5 parameters from artist search (can just pass the URL or MD5 hash to the name parameter)

1.8.1

• Removed post[is_flagged] attribute