Derpibooru Import is running again! All imported content is tagged as 'derpibooru import' and has the original tags.
Welcome to Twibooru! Anonymous posting only; no content restrictions beyond pony-related and legal; comments are disabled by default (Settings -> Comments). Read me!

API

Last updated

We provide 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 the site.

The API is basically identical to that in use on Derpibooru prior to 2020. As such, any applications written for that API should be easily modifiable to be compatible with our API.

Licensing

Licensing of the API is simple — anyone can use it. However, there are some guidelines we ask that you follow:

  • Do not make abusively high numbers of requests
  • Your application MUST properly cache and respect server-side cache expiry times
  • Your client MUST gracefully back off if requests fail (e.g., non-200 OK HTTP status code), preferably exponentially or fatally
  • Credit SHOULD be given to Twibooru in the form of a link
  • If media is displayed from Twibooru, the artist SHOULD be credited (if available) and you SHOULD display the original source URL with the media, either textually or as a link
  • A link to the item page here on Twibooru is optional but suggested
  • We recommend using twibooru.org as the canonical domain
  • The https protocol MUST be specified on all URIs; we do not support plain text HTTP connections

Accessing the API

Most methods support API access by appending the .json extension 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 and can be found by users on their account page. For instance, to access a user's watched feed, the request would be /images/watched.json?key=xxxxxxxxxxxxxxxxxxxx

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 use a custom filter, you can use the filter_id parameter.

Libraries

There are currently no libraries that have been written for the Twibooru API; however, you may be able to find old versions of some of the Derpibooru API libraries listed below and make them work with Twibooru with minor modifications. We haven't tested any of them, so your results may vary. If you want to develop or port one of these to Twibooru, please do so and contact us if you'd like a library you've written for us to be included in this list.

Available Methods

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

/images.json
Lists all items
/470155.json
Will get the metadata for a particular item
/search.json?q=twilight+sparkle
Returns the results of a search for the tag twilight sparkle
/search.json?q=twilight+sparkle&page=2
Returns page 2 of the results for the search for the tag twilight sparkle
/search.json?q=created_at.gt:3+days+ago
Returns items where the created_at date is greater than 3 days ago

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

Authenticated requests take a key argument. Fill this in with your personal API key from your Account page.

  • /images/watched.json?key=xxxxxxxxxxxxxxxxxxxx
  • /search.json?q=my:faves&key=xxxxxxxxxxxxxxxxxxxx
  • /search.json?q=my:upvotes&key=xxxxxxxxxxxxxxxxxxxx

Available Parameters

Image Index (/images.json)

Parameter Function
page The page offset, indexed from 1. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)
deleted When 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.
random_image When set, order the images randomly.

Image Search (/search.json)

Parameter Function
q The search query. (Replace spaces with +.)
page The page offset, indexed from 1. (Refer to Image Index section for more information.)
perpage How many results to return on each page (must be between 1 and 50).

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 /oembed.json or /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 Twibooru.

In addition to the standard oEmbed photo attributes, the following attributes are also provided: twibooru_id, twibooru_score, and twibooru_comments

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

  • https://twibooru.org/*
  • https://twibooru.org/images/*
  • https://cdn.twibooru.org/img/*

For example:

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

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

Revision history