API Deprecation Notice: We are retiring the previous version of our API. Please make sure you update your third party apps! More info

API

Last updated

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

Revision history