API

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.

• Philomena4J (COMING SOON) - By Floorb, supports Twibooru natively (Java).

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", "video/mp4".
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, eg: oc:blackjack.
name_in_namespace	String	The name of the tag in its namespace, eg: blackjack.
namespace	String	The namespace of the tag, eg: oc.
short_description	String	The short description for the tag.
slug	String	The URL slug for the tag, eg: -fwslash-mlp-fwslash-.

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:

• /oembed.json?url=https://twibooru.org/470155

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.