Bronibooru 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.
Basics
HTTP defines four basic request methods: GET, POST, PUT and DELETE. You'll be using these methods to interact with the Bronibooru 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 will be passing these parameters along in the body instead of the query parameters.
Responses
All API calls that change state will return a single element response (for XML calls). They are formatted 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, Bronibooru uses some custom status codes in the 4xx and 5xx range.
200 OK: Request was successful
204 No Content: Request was successful
403 Forbidden: Access denied
404 Not Found: Not found
420 Invalid Record: Record could not be saved
421 User Throttled: User is throttled, try again later
422 Locked: The resource is locked and cannot be modified
423 Already Exists: Resource already exists
424 Invalid Parameters: The given parameters were invalid
500 Internal Server Error: Some unknown error occurred on the server
503 Service Unavailable: Server cannot currently handle the request, try again later
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.
Queries
Posts
Listing
The base URL is GET /posts.json.
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.
raw 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.
Show
The base URL is GET /posts/$id.json where $id is the post id.
Create
You cannot directly create posts. You must create an upload, which is then converted into a post.
Update
The base URL is PUT /posts/$id.json where $id is the post id.
post[tag_string] A space delimited list of tags.
post[rating] The rating for the post. Can be: safe, questionable, or explicit.
post[source] If this is a URL, Bronibooru will download the file.
post[parent_id] The ID of the parent post.
Delete
You cannot delete posts. You can only flag them for deletion (see PostFlag resource).
Revert
The base URL is PUT /posts/$id/revert.json where $id is the post id.
version_id REQUIRED The post version id to revert to.
Copy notes
The base URL is PUT /posts/$id/copy_notes.json where $id is the post id.
other_post_id REQUIRED The id of the post to copy notes to.
Post Votes
Create
The base URL is POST /posts/$post_id/votes.json where $post_id is the post id.
score REQUIRED Can be: up, down.
Post Flags
Listing
The base URL is GET /post_flags.json.
search[creator_id] The user id of the flag's creator.
search[creator_name] The name of the flag's creator.
search[post_id] The post id if the flag.
Create
The base URL is POST /post_flags.json.
post_flag[post_id] REQUIRED The id of the flagged post.
post_flag[reason] REQUIRED The reason of the flagging.
Post Appeals
Listing
The base URL is GET /post_appeals.json.
search[creator_id] The user id of the appeal's creator.
search[creator_name] The name of the appeal's creator.
search[post_id] The post id if the appeal.
Create
The base URL is POST /post_appeals.json.
post_appeal[post_id] REQUIRED The id of the appealed post.
post_appeal[reason] REQUIRED The reason of the appeal.
Uploads
Listing
The base URL is GET /uploads.json.
search[uploader_id] The id of the uploader.
search[uploader_name] The name of the uploader.
search[source] The source of the upload (exact string match).
Show
The base URL is GET /uploads/$id.json where $id is the upload id.
Create
The base URL is POST /uploads.json.
upload[file] The file data encoded as a multipart form.
upload[source] The source URL.
upload[rating] REQUIRED Can be: safe, questionable, explicit.
upload[parent_id] The parent post id.
upload[tag_string] REQUIRED The tags.
Either the file or the source must be provided.
Comments
Listing
The base URL is GET /comments.json.
group_by Must be: comment
search[body_matches] Body contains the given terms.
search[post_id]
search[post_tags_match] The comment's post's tags match the given terms. Meta-tags not supported.
search[creator_name] The name of the creator (exact match)
search[creator_id] The user id of the creator
Create
The base URL is POST /comments.json
comment[post_id] REQUIRED
comment[body] REQUIRED
comment[do_not_bump_post] Set to 1 if you do not want the post to be bumped to the top of the comment listing
Update
The base URL is PUT /comments/$id.json where $id is the comment id.
comment[body] REQUIRED
comment[do_not_bump_post] Set to 1 if you do not want the post to be bumped to the top of the comment listing
Show
The base URL is GET /comments/$id.json where $id is the comment id.
Delete
The base URL is DELETE /comments/$id.json where $id is the comment id.
Dmails
Listing
The base URL is GET /dmails.json. You can only view dmails you own.
search[message_matches] The message body contains the given terms.
search[to_name] The recipient's name.
search[to_id] The recipient's user id.
search[from_name] The sender's name.
search[from_id] The sender's user id.
search[read] Can be: true, false
Show
The base URL is GET /dmails/$id.json where $id is the dmail id. You can only view dmails you own.
Create
The base URL is POST /dmails.json.
dmail[to_name] The recipient's name.
dmail[title] The title of the message.
dmail[body] The body of the message.
Delete
The base URL is DELETE /dmails/$id.json where $id is the dmail id. You can only delete dmails you own.
Artists
Listing
The base URL is GET /artists.json.
search[name] This field has multiple uses depending on what the query starts with:
http Search for artist with this URL.
name: Search for artists with the given name as their base name..
other: Search for artists with the given name in their other names.
group: Search for artists belonging to the group with the given name.
status:banned Search for artists that are banned.
else Search for the given name in the base name and the other names.
search[id] The artist id.
search[creator_name]
search[creator_id]
search[is_active] Can be: true, false
search[is_banned] Can be: true, false
search[empty_only] Search for artists that have 0 posts. Can be: true
search[order] Can be: name, date.
Show
The base URL is GET /artists/$id.json where $id is the artist id.
Create
The base URL is POST /artists.json.
artist[name]
artist[other_names_comma] List of alternative names for this artist, comma delimited.
artist[group_name] The name of the group this artist belongs to.
artist[url_string] List of URLs associated with this artist, whitespace or newline delimited.
Update
The base URL is PUT /artists/$id.json where $id is the artist id.
artist[name]
artist[other_names_comma] List of alternative names for this artist, comma delimited.
artist[group_name] The name of the group this artist belongs to.
artist[url_string] List of URLs associated with this artist, whitespace or newline delimited.
Delete
The base URL is DELETE /artists/$id.json where $id is the artist id.
Banned
The base URL is GET /artists/banned.json. This is a shortcut for an artist listing search with name=status:banned.
Revert
The base URL is PUT /artists/$id/revert.json where $id is the artist id.
version_id REQUIRED The artist version id to revert to.
Notes
Listing
The base URL is GET /notes.json.
search[body_matches] The note's body matches the given terms.
search[post_id]
search[post_tags_match] The note's post's tags match the given terms. Meta-tags are not supported.
search[creator_name] The creator's name. Exact match.
search[creator_id] The creator's user id.
Use /notes.json?group_by=note&search[post_id]=$id to get notes from $id.
Show
The base URL is GET /notes/$id.json where $id is the note id.
Create
note[post_id] REQUIRED
note[x] REQUIRED The x coordinates of the note in pixels, with respect to the top-left corner of the image.
note[y] REQUIRED The y coordinates of the note in pixels, with respect to the top-left corner of the image.
note[width] REQUIRED The width of the note in pixels.
note[height] REQUIRED The height of the note in pixels.
note[body] REQUIRED The body of the note.
Update
The base URL is PUT /notes/$id.json where $id is the note id.
note[x] The x coordinates of the note in pixels, with respect to the top-left corner of the image.
note[y] The y coordinates of the note in pixels, with respect to the top-left corner of the image.
note[width] The width of the note in pixels.
note[height] The height of the note in pixels.
note[body] The body of the note.
Delete
The base URL is DELETE /notes/$id.json where $id is the note id.
Revert
The base URL is PUT /notes/$id/revert.json where $id is the note id.
version_id REQUIRED The note version id to revert to.
Users
Levels
Users have a number attribute called level representing their role. The current levels are:
Member: 20
Gold: 30
Platinum: 31
Builder: 32
Contributor: 33
Janitor: 35
Moderator: 40
Admin: 50
Listing
The base URL is GET /users.json.
search[name] Supports patterns.
search[min_level] Minimum level (see section on levels).
search[max_level] Maximum level (see section on levels).
search[level] Current level (see section on levels).
search[id] The user id.
search[order] Can be: name, post_upload_count, note_count, post_update_count, date.
Show
The base URL is GET /users/$id.json where $id is the user id.
Post Versions
Listing
The base URL is GET /post_versions.json.
search[updater_name]
search[updater_id]
search[post_id]
search[start_id]
Note Versions
Listing
The base URL is GET /note_versions.json.
search[updater_id]
search[post_id]
search[note_id]
Artist Versions
Listing
The base URL is GET /artist_versions.json.
search[name]
search[updater_id]
search[artist_id]
search[is_active] Can be: true, false
search[is_banned] Can be: true, false
search[order] Can be: name, date
Pools
Listing
The base URL is GET /pools.json.
search[name_matches]
search[description_matches]
search[creator_name]
search[creator_id]
search[is_active] Can be: true, false
search[order] Can be: name, created_at, post_count, date
search[category] Can be: series, collection
Show
The base URL is GET /pools/$id.json where $id is the pool id.
Create
The base URL is POST /pools.json.
pool[name] REQUIRED
pool[description] REQUIRED
pool[category] Can be: series, collection
Update
The base URL is PUT /pools/$id.json where $id is the pool id.
pool[name]
pool[description]
pool[post_ids] List of space delimited post ids.
pool[is_active] Can be: 1, 0
pool[category] Can be: series, collection
Delete
The base URL is DELETE /pools/$id.json where $id is the pool id.
Undelete
The base URL is POST /pools/$id/undelete.json where $id is the pool id.
Revert
The base URL is PUT /pools/$id/revert.json where $id is the pool id.
version_id REQUIRED
Pool Versions
Listing
The base URL is GET /pool_versions.json.
search[updater_id]
search[updater_name]
search[pool_id]
Tags
Listing
The base URL is GET /tags.json.
search[name_matches]
search[category] Can be: 0, 1, 3, 4 (general, artist, copyright, character respectively)
search[hide_empty] Can be: yes, no. Excludes tags with 0 posts when "yes".
search[order] Can be: name, date, count
search[has_wiki] Can be: yes, no
search[name] 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.
Tag Aliases
Listing
The base URL is GET /tag_aliases.json.
search[name_matches] Match antecedent or consequent name.
search[antecedent_name] Match antecedent name (exact match).
search[id] The tag alias id.
Tag Implications
Listing
The base URL is GET /tag_implications.json.
search[name_matches] Match antecedent or consequent name.
search[antecedent_name] Match antecedent name (exact match).
search[id] The tag implication id.
Wiki Pages
Listing
The base URL is GET /wiki_pages.json.
search[title]
search[creator_id]
search[body_matches]
search[other_names_match]
search[creator_name]
search[order] Can be: date, title.
Show
The base URL is GET /wiki_pages/$id.json where $id is the wiki page id.
Create
The base URL is POST /wiki_pages.json.
wiki_page[title] REQUIRED
wiki_page[body] REQUIRED
wiki_page[other_names]
Update
The base URL is PUT /wiki_pages/$id.json where $id is the wiki page id.
wiki_page[title]
wiki_page[body]
wiki_page[other_names]
Revert
The base URL is PUT /wiki_pages/$id/revert.json where $id is the wiki page id.
version_id REQUIRED
Related Tags
Show
The base URL is GET /related_tag.json.
query REQUIRED The tag to find the related tags for.
category If specified, show only tags of a specific category. Can be:
General 0
Artist 1
Copyright 3
Character 4
Forum Topics
Listing
The base URL is GET /forum_topics.json.
search[title_matches] Search body for the given terms.
search[title] Exact title match.
search[category_id] Can be: 0, 1, 2 (General, Tags, Bugs & Features respectively)
Show
The base URL is GET /forum_topics/$id.json where $id is the forum topic id.
Create
The base URL is POST /forum_topics.json.
forum_topic[title]
forum_topic[original_post_attributes][body] Message of the initial post.
forum_topic[category_id]
Update
The base URL is PUT /forum_topics/$id.json where $id is the forum topic id.
forum_topic[title]
forum_topic[category_id]
Delete
The base URL is DELETE /forum_topics/$id.json where $id is the forum topic id.
Undelete
The base URL is POST /forum_topics/$id/undelete.json where $id is the forum topic id.
Forum Posts
Listing
The base URL is GET /forum_posts.json.
search[creator_id]
search[creator_name]
search[topic_id]
search[topic_title_matches]
search[topic_category_id] Can be: 0, 1, 2 (General, Tags, Bugs & Features respectively)
search[body_matches]
Create
The base URL is POST /forum_posts.json.
forum_post[body]
Update
The base URL is PUT /forum_posts/$id.json where $id is the forum post id.
forum_post[body]
Delete
The base URL is DELETE /forum_posts/$id.json where $id is the forum post id.
Undelete
The base URL is POST /forum_posts/$id/undelete.json where $id is the forum post id.
Artist Commentary
Listing
The base URL is GET /artist_commentaries.json.
search[text_matches]
search[post_tags_match] The commentary's post's tags match the given terms. Meta-tags not supported.
search[original_present] Can be: yes, no
search[translated_present] Can be: yes, no
Create or Update
The base URL is POST /artist_commentaries/create_or_update.json
artist_commentary[post_id] REQUIRED
artist_commentary[original_title]
artist_commentary[original_description]
artist_commentary[translated_title]
artist_commentary[translated_description]
Revert
The base URL is PUT /artist_commentaries/$id/revert.json where $id is the post id (not the artist commentary id).
version_id REQUIRED The artist commentary version id to revert to.
Artist Commentary Versions
Listing
The base URL is GET /artist_commentary_versions.json.