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 similar to that in use on Derpibooru and other Philomena-based boorus. 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. Respect the rate limits.
  • 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 post 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

Parameters

This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.

Name Description
filter_id Assuming the user can access the filter ID given by the parameter, overrides the current filter for this request. This is primarily useful for unauthenticated API access.
key An optional authentication token. If omitted, no user will be authenticated.

You can find your authentication token in your account settings.
page Controls the current page of the response, if the response is paginated. Empty values default to the first page.
per_page Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.
q The current search query, if the request is a search request.
sd The current sort direction, if the request is a search request.
sf The current sort field, if the request is a search request.

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 /posts/watched.json?key=xxxxxxxxxxxxxxxxxxxx

Methods dealing with large feeds are paginated; the page parameter controls the page you're on. The number of posts 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 is currently only one specific library that has been written for the Twibooru API. You may be able to adapt 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 it included in this list.

Routes

Method Path Allowed Query Parameters Description Response Format Example
GET /api/v3/posts/:post_id key, filter_id Fetches a post response for the post ID referenced by the post_id URL parameter. {"post":post-response} /api/v3/posts/1
GET /api/v3/posts/featured Fetches a post response for the for the current featured image. {"post":post-response} /api/v3/posts/featured
GET /api/v3/posts/:post_id/comments Fetches a list of comment responses representing all comments on the post referenced by the post_id URL parameter. {"comments":[comment-response]} /api/v3/posts/1/comments
GET /api/v3/search/posts key, filter_id, page, per_page, q, sd, sf Executes the search given by the q query parameter, and returns a list of post responses. {"posts":[post-response]} /api/v3/search/posts?q=safe
GET /api/v3/search/tags page, per_page, q Executes the search given by the q query parameter, and returns a list of tag responses, sorted by descending image count. {"tags":[tag-response]} /api/v3/search/tags?q=*wing*

Post Responses

These fields are present on all posts (unless otherwise noted), whether they have been hidden or not.

Field Type Description
created_at RFC3339 datetime The creation time, in UTC, of the post.
deletion_reason String The hide reason for the post, or null if none provided. This will only be present on posts which have been deleted for a rule violation.
duplicate_of Integer The ID of the target post this post has been merged into. This will only be present on posts which have been merged into another post.
first_seen_at RFC3339 datetime The time, in UTC, the post was first seen (before any duplicate merging).
hidden_from_users Boolean Whether the post is hidden. A post is hidden if it is merged or deleted for a rule violation.
id Integer The post's ID.
locations Array<Object> Array of location objects, providing information about other websites this image may be found on.
media_type String The type of media associated with this post. One of "paste", "image".
orig_sha512_hash String The SHA512 hash of the post as it was originally uploaded.
processed Boolean Whether the post has finished background processing.
sha512_hash String The SHA512 hash of this post after it has been processed.
source_url String The current source URL of the post.
tag_ids Array A list of tag IDs the post contains.
tags Array A list of tag names the post contains.
updated_at RFC3339 datetime The time, in UTC, the post was last updated.

Non-hidden Post Responses

For posts which are not hidden (ie: most posts), the following fields are also present in the response:

Field Type Description
comment_count Integer The number of comments the post has.
description String The post's description.
downvotes Integer The number of downvotes the post has.
faves Integer The number of favourites the post has.
first_seen_at RFC3339 datetime The time, in UTC, the post was first seen (before any duplicate merging).
score Integer The post's score - usually the number of upvotes minus the number of downvotes.
size Integer The number of bytes the post's file contains.
source_url String The current source URL of the post.
upvotes Integer The post's number of upvotes.
wilson_score Float The lower bound of the Wilson score interval for the post, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.

Image Post Responses

For non-hidden posts where media_type is equal to "image", the following fields are also present in the response:

Field Type Description
animated Boolean Whether the image is animated.
aspect_ratio Float The image's width divided by its height.
duration Float The number of seconds the animation lasts, if animated, otherwise 0. (Currently unreliable.)
format String The file extension of the image. One of "gif", "jpg", "jpeg", "png", "svg", "webm", "mp4".
height Integer The image's height, in pixels.
intensities Object Optional object of internal image intensity data for deduplication purposes. May be null if intensities have not yet been generated.
mime_type String The MIME type of this image. One of "image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm".
name String The filename that the image was uploaded with.
representations Object A mapping of representation names to their respective URLs. Contains the keys "full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny".
thumbnails_generated Boolean Whether the image has finished thumbnail generation. Do not attempt to load images from view_url or representations if this is false.
view_url String The image's view URL, including tags.
width Integer The image's width, in pixels.

Tag Responses

Field Type Description
aliased_tag String The name of the tag this tag is aliased to, if any.
aliases Array The names of the tags aliased to this tag.
category String The category class of this tag. One of "character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler".
description String The long description for the tag.
id Integer The tag's ID.
images Integer The post count of the tag.
implied_by_tags Array The names of the tags this tag is implied by.
implied_tags Array The names of the tags this tag implies.
name String The name of the tag.
name_in_namespace String The name of the tag in its namespace.
namespace String The namespace of the tag.
short_description String The short description for the tag.
slug String The slug for the tag.

Intensities Objects

Meaning can be given to these fields by understanting the source code. Please note that these values are NOT compatible with the values generated by the newer cli_intensities tool, which is used by Philomena.

Field Type Description
nw Float The north-west intensity of the image.
ne Float The north-east intensity of the image.
sw Float The south-west intensity of the image.
se Float The south-east intensity of the image.

Location Objects

Field Type Description
id_at_location Integer The identifier, specific to the site named in location, associated with this post's equivalent on the other site.
location String Name of site that this location describes. May be one of derpibooru, ponybooru, rainbooru, ponerpics, foalcon, lyrabooru, manebooru. Currently only derpibooru is returned.
url_at_location String A URL to the human-readable page at which this post can be found at the described location.

Rate Limits

There are hard rate limits enforced on every API endpoint. Exceeding these limits will result in your requests being throttled until the rate limit is complied with.

You can determine the rate limit and your remaining balance, as well as the time at which the balance will reset, by examining the X-RL, X-RL-Remaining, and X-RL-Reset HTTP headers, respectively. For convenience, here is a list of rate limits:

Endpoint Maximum Requests Period
/api/v3/search/posts 10 1 minute
/api/v3/search/tags 60 1 minute
/api/v3/posts/:id 60 1 minute
/api/v3/posts/:id/comments 60 1 minute

Errors

The API may return various HTTP error codes, either due to server or client error. When an error code is returned, the server will respond with a JSON payload containing an error key with a string value, textually describing the error that occured.

Error Code Description Resolution
401 Unauthorized You attempted to retrieve a resource you are not authorized to retrieve. Ensure you have provided appropriate credentials.
404 Not Found You attempted to retrieve a resource that does not exist. Only attempt to retrieve resources that exist.
422 Unprocessable Entity A query was sent to the server in an invalid format (eg: imbalanced parentheses in search term.) Format the query correctly.
429 Too Many Requests Too many queries were sent to the server in too short of a time. Wait some time and re-try the request. Utilize the rate limit headers to avoid encountering this error.
500 Internal Server Error An unknown server-side error occured while processing your request. Contact a site administrator for help.

oEmbed

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

This API is compliant with 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 post'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/posts/*
  • 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