Bronibooru

Read the rules before proceeding!

help:api

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:

<?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, 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