Pony with extra care The rest of the season has leaked, be sure to add corresponding tags to filters and images, including the "leak" tag

API

Derpibooru provides a JSON API for major site functionality, which can be freely used by anyone wanting to produce tools for the site or other webapps that use the data provided within Derpibooru.

Licensing

Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.

Credit MUST always be given to the site in the form of a link. If images are used, the artist MUST always be credited (if provided) and the original source URL MUST be displayed alongside the image, either in textual form or as a link. A link to the Derpibooru page is optional but recommended; we recommend the derpibooru.org domain as a canonical domain. The https protocol MUST be specified on all URIs; Derpibooru does not support plaintext HTTP connections.

Accessing the API

Most methods support API access by appending the extension .json to a URL. For requests that require authentication, the URL parameter "key" should be appended. This key provides limited access to a user"s account. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request /images/watched.json?key=yourkey would be made.

Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images per page can be set with the "perpage" parameter. The default is 15 unless you use your key and have changed the "Images per page" option on the settings page.

Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.

Libraries

Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.

Available Methods

Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add .json to the end of the path. Here are a few incredibly exciting examples.

Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.

Authenticated requests take a key argument - your personal key is shown in these requests as an example.

Available Parameters

All page parameters are 1-indexed.

Image Index (/images.json)

ParameterFunction
constraintSearch and sort by a specific field. (See also the note on page offsets below.)
Currently, the field can be:
  • id - to search by ID number
  • updated - to search by last update time
  • created - to search by image creation time
Time fields are in ISO 8601 format (the same format which is returned).
pageThe page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)
gtWhen specified, constraint field must be greater than this value.
gteWhen specified, constraint field must be greater than or equal to this value.
ltWhen specified, constraint field must be less than this value.
lteWhen specified, constraint field must be less than or equal to this value.
orderSort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.
deletedWhen set, includes limited information about deleted and duplicate images in the results.For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
commentsWhen set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.
favWhen set, include favorited-by arrays. Only enable this if you really need it.
random_imageWhen set, order the images randomly.

Image Lists (/lists.json, /lists/top_scoring.json, etc.)

ParameterFunction
pageThe page offset. (Refer to Image Index section for more information.)
lastSampling period, specified in weeks, days, or hours.
commentsWhen set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.
favWhen set, include favorited-by arrays. Only enable this if you really need it.

Image Search (/search.json)

ParameterFunction
qThe search query. (Replace spaces with "+".)
pageThe page offset. (Refer to Image Index section for more information.)
commentsWhen set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.
favWhen set, include favorited-by arrays. Only enable this if you really need it.

Image Galleries

/galleries/{user_name}.json

Returns all galleries belonging to the specified user.

ParameterFunction
pageThe page offset. (Showing 20 items per page.)
include_imagesWhen set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.

/galleries/{user_name}/{gallery_id}.json

Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with include_images parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.Content filters are respected as well.

Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.

ParameterFunction
pageThe page offset. (Refer to Image Index section for more information.)

oEmbed

For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.

This API is compliant to the oEmbed specification and can be found at https://derpibooru.org/oembed.json or https://derpibooru.org/oembed.xml

Format selection is done by URL; call oembed.xml for an XML response. This is the only API currently supporting XML and we strongly encourage the use of JSON wherever possible.

You are strongly advised to cache response data on your own server upon embedding content via oEmbed, particularly if your website supports a large number of users. A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.

The author_url and author_name attributes will be set to the original author/source URL attributes wherever possible. The provider_url attribute will always direct you to the image's page on Derpibooru.

In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments

The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.

  • https://derpibooru.org/*
  • https://derpibooru.org/images/*
  • https://trixiebooru.org/*
  • https://trixiebooru.org/images/*
  • https://derpicdn.net/img/*

For example:

This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.

For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.