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 web applications that use the data provided within Derpibooru.

Note that if you are looking to continuously scrape the entire website, we offer nightly database dumps instead. Consider if these suit your needs first, then rely on the API if they do not.

Licensing

Anyone may use the API. Users making abusively high numbers of requests or excessively expensive requests will be asked to stop, and banned if they do not. Your application must properly cache, and respect server-side cache expiry times. Your client must gracefully back off if requests fail, preferably exponentially or fatally.

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 URLs.

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.

Routes

The interested reader may find the implementations of these endpoints here. For the purposes of this document, a brief overview is given.

Method	Path	Allowed Query Parameters	Description	Response Format	Example
GET	/api/v1/json/comments/:comment_id		Fetches a comment response for the comment ID referenced by the comment_id URL parameter.	{"comment":comment-response}	/api/v1/json/comments/1000
GET	/api/v1/json/images/:image_id	key, filter_id	Fetches an image response for the image ID referenced by the image_id URL parameter.	{"image":image-response}	/api/v1/json/images/1
GET	/api/v1/json/oembed	url	Returns an oEmbed response for the given app link or CDN URL.	oembed-response	/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png
GET	/api/v1/json/search/comments	key, page	Executes the search given by the q query parameter, and returns comment responses sorted by descending creation time.	{"comments":[comment-response]}	/api/v1/json/search/comments?q=image_id:1000000
GET	/api/v1/json/search/galleries	key, page	Executes the search given by the q query parameter, and returns gallery responses sorted by descending creation time.	{"galleries":[gallery-response]}	/api/v1/json/search/galleries?q=title:mean*
GET	/api/v1/json/search/posts	key, page	Executes the search given by the q query parameter, and returns post responses sorted by descending creation time.	{"posts":[post-response]}	/api/v1/json/search/posts?q=subject:time wasting thread
GET	/api/v1/json/search/images	key, filter_id, page, per_page, q, sd, sf	Executes the search given by the q query parameter, and returns image responses.	{"images":[image-response]}	/api/v1/json/search/images?q=safe
GET	/api/v1/json/search/tags	page	Executes the search given by the q query parameter, and returns tag responses sorted by descending image count.	{"tags":[tag-response]}	/api/v1/json/search/tags?q=analyzed_name:wing
POST	/api/v1/json/search/reverse	key, url	Returns image responses based on the results of reverse-searching the image given by the url query parameter.	{"images":[image-response]}	/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg
GET	/api/v1/json/tags/:tag_id	key	Returns a tag response for the tag slug given by the tag_id URL parameter. The tag's ID is not used.	{"tag":tag-response}	/api/v1/json/tags/artist-colon-atryl

Image Responses

Field	Type	Description
aspect_ratio	Float	The image's width divided by its height.
comment_count	Integer	The number of comments made on the image.
created_at	RFC3339 datetime	The creation time, in UTC, of the image.
deletion_reason	String	The hide reason for the image, or null if none provided. This will only have a value on images which are deleted for a rule violation.
description	String	The image's description.
downvotes	Integer	The number of downvotes the image has.
duplicate_of	Integer	The ID of the target image, or null if none provided. This will only have a value on images which are merged into another image.
faves	Integer	The number of faves the image has.
first_seen_at	RFC3339 datetime	The time, in UTC, this image was first seen (before any duplicate merging).
format	String	The file extension of this image. One of "gif", "jpg", "png", "svg", "webm".
height	Integer	The image's height, in pixels.
hidden_from_users	Boolean	Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.
id	Integer	The image's ID.
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 this image was uploaded with.
orig_sha512_hash	String	The SHA512 hash of this image as it was originally uploaded.
processed	Boolean	Whether the image has finished optimization.
representations	Object	A mapping of representation names to their respective URLs. Contains the keys "full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny".
score	Integer	The image's number of upvotes minus the image's number of downvotes.
sha512_hash	String	The SHA512 hash of this image after it has been processed.
source_url	String	The current source URL of the image.
spoilered	Boolean	Whether this image is hit by the current filter.
tag_count	Integer	The number of tags present on this image.
tag_ids	Array	A list of tag IDs this image contains.
tags	Array	A list of tag names this image contains.
thumbnails_generated	Boolean	Whether this image has finished thumbnail generation. Do not attempt to load images from view_url or representations if this is false.
updated_at	RFC3339 datetime	The time, in UTC, the image was last updated.
uploader	String	The image's uploader.
uploader_id	Integer	The ID of the image's uploader.
upvotes	Integer	The image's number of upvotes.
view_url	String	The image's view URL, including tags.
width	Integer	The image's width, in pixels.
wilson_score	Float	The lower bound of the Wilson score interval for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.

Comment Responses

Field	Type	Description
author	String	The comment's author.
body	String	The comment text.
id	Integer	The comment's ID.
image_id	Integer	The ID of the image the comment belongs to.
user_id	Integer	The ID of the user the comment belongs to, if any.

Post Responses

Field	Type	Description
author	String	The post's author.
body	String	The post text.
id	Integer	The post's ID.
topic_id	Integer	The ID of the topic the post belongs to.
user_id	Integer	The ID of the user the comment belongs to, if any.

Tag Responses

Field	Type	Description
aliased_tag	String	The slug of the tag this tag is aliased to, if any.
aliases	Array	The slugs 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.
dnp_entries	Array	An array of objects containing DNP entries claimed on the tag.
id	Integer	The tag's ID.
images	Integer	The image count of the tag.
implied_by_tags	Array	The slugs of the tags this tag is implied by.
implied_tags	Array	The slugs 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.
spoiler_image	String	The spoiler image URL for the tag.

Gallery Responses

Field	Type	Description
description	String	The gallery's description.
id	Integer	The gallery's ID.
spoiler_warning	String	The gallery's spoiler warning.
thumbnail_id	Integer	The ID of the cover image for the gallery.
title	String	The gallery's title.
user	String	The name of the gallery's creator.
user_id	Integer	The ID of the gallery's creator.

Oembed Responses

Field	Type	Description
author_name	String	The comma-delimited names of the image authors.
author_url	String	The source URL of the image.
cache_age	Integer	Always 7200.
derpibooru_comments	Integer	The number of comments made on the image.
derpibooru_id	Integer	The image's ID.
derpibooru_score	Integer	The image's number of upvotes minus the image's number of downvotes.
derpibooru_tags	Array	The names of the image's tags.
provider_name	String	Always "Derpibooru".
provider_url	String	Always "https://derpibooru.org".
title	String	The image's ID and associated tags, as would be given on the title of the image page.
type	String	Always "photo".
version	String	Always "1.0".