Ponybooru 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 Ponybooru.
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 Ponybooru page is optional but recommended; we recommend the ponybooru.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 |
POST |
/api/v1/json/images |
key, url |
Submits a new image. Both key and url are required. Errors will result in an {"errors":image-errors-response}. |
{"image":image-response} |
Posting images |
GET |
/api/v1/json/images/featured |
|
Fetches an image response for the for the current featured image. |
{"image":image-response} |
/api/v1/json/images/featured |
GET |
/api/v1/json/tags/:tag_id |
|
Fetches 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 |
GET |
/api/v1/json/posts/:post_id |
|
Fetches a post response for the post ID given by the post_id URL parameter. |
{"post":post-response} |
/api/v1/json/posts/2730144 |
GET |
/api/v1/json/profiles/:user_id |
|
Fetches a profile response for the user ID given by the user_id URL parameter. |
{"user":user-response} |
/api/v1/json/profiles/216494 |
GET |
/api/v1/json/filters/:filter_id |
key |
Fetches a filter response for the filter ID given by the filter_id URL parameter. |
{"filter":filter-response} |
/api/v1/json/filters/56027 |
GET |
/api/v1/json/filters/system |
page |
Fetches a list of filter responses that are flagged as being system filters (and thus usable by anyone). |
{"filters":[filter-response]} |
/api/v1/json/filters/system |
GET |
/api/v1/json/filters/user |
key, page |
Fetches a list of filter responses that belong to the user given by key. If no key is given or it is invalid, will return a 403 Forbidden error. |
{"filters":[filter-response]} |
/api/v1/json/filters/user |
GET |
/api/v1/json/oembed |
url |
Fetches 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, distance |
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/forums |
|
Fetches a list of forum responses. |
{"forums":forum-response} |
/api/v1/json/forums |
GET |
/api/v1/json/forums/:short_name |
|
Fetches a forum response for the abbreviated name given by the short_name URL parameter. |
{"forum":forum-response} |
/api/v1/json/forums/dis |
GET |
/api/v1/json/forums/:short_name/topics |
page |
Fetches a list of topic responses for the abbreviated forum name given by the short_name URL parameter. |
{"topics":topic-response} |
/api/v1/json/forums/dis/topics |
GET |
/api/v1/json/forums/:short_name/topics/:topic_slug |
|
Fetches a topic response for the abbreviated forum name given by the short_name and topic given by topic_slug URL parameters. |
{"topic":topic-response} |
/api/v1/json/forums/dis/topics/ask-the-mods-anything |
GET |
/api/v1/json/forums/:short_name/topics/:topic_slug/posts |
page |
Fetches a list of post responses for the abbreviated forum name given by the short_name and topic given by topic_slug URL parameters. |
{"posts":post-response} |
/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts |
GET |
/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id |
|
Fetches a post response for the abbreviated forum name given by the short_name, topic given by topic_slug and post given by post_id URL parameters. |
{"post":post-response} |
/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095 |
Posting Images
Posting images should be done via request body parameters. An example with all parameters included is shown below.
You are strongly recommended to test code using this endpoint using a local copy of the website's source code. Abuse of the endpoint will result in a ban.
You must provide the direct link to the image in the url parameter.
You must set the content-type header to application/json for the site to process your request.
POST /api/v1/json/images?key=API_KEY
{
"image": {
"description": "[bq]Hey there this is a test post![/bq]\nDescriptions are *weird*.\nHave a >>0 re-upload :)\n",
"tag_input": "artist needed, safe, derpy hooves, pegasus, pony, adventure in the comments, bag, building, chair, cigar, ponybooru legacy, eyes, featured image, female, grin, gritted teeth, hilarious in hindsight, image macro, it begins, j. jonah jameson, letter, mail, male, mare, meme, muffin, necktie, paper, parody, phone, ponified, sitting, smiling, smoking, song in the comments, spider-man, stallion, swinging",
"source_url": "https://ponybooru.org/images/0"
},
"url": "https://derpicdn.net/img/view/2012/1/2/0.jpg"
}
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", "jpeg", "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. null if uploaded anonymously. |
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%. |
| Field |
Type |
Description |
author |
String |
The comment's author. |
avatar |
String |
The URL of the author's avatar. May be a link to the CDN path, or a data: URI. |
body |
String |
The comment text. |
created_at |
RFC3339 datetime |
The creation time, in UTC, of the comment. |
edit_reason |
String |
The edit reason for this comment, or null if none provided. |
edited_at |
RFC3339 datetime |
The time, in UTC, this comment was last edited at, or null if it was not edited. |
id |
Integer |
The comment's ID. |
image_id |
Integer |
The ID of the image the comment belongs to. |
updated_at |
RFC3339 datetime |
The time, in UTC, the comment was last updated at. |
user_id |
Integer |
The ID of the user the comment belongs to, if any. |
Forum Responses
| Field |
Type |
Description |
name |
String |
The forum's name. |
short_name |
String |
The forum's short name (used to identify it). |
description |
String |
The forum's description. |
topic_count |
Integer |
The amount of topics in the forum. |
post_count |
Integer |
The amount of posts in the forum. |
Topic Responses
| Field |
Type |
Description |
slug |
String |
The topic's slug (used to identify it). |
title |
String |
The topic's title. |
post_count |
Integer |
The amount of posts in the topic. |
view_count |
Integer |
The amount of views the topic has received. |
sticky |
Boolean |
Whether the topic is sticky. |
last_replied_to_at |
RFC3339 datetime |
The time, in UTC, when the last reply was made. |
locked |
Boolean |
Whether the topic is locked. |
user_id |
Integer |
The ID of the user who made the topic. null if posted anonymously. |
author |
String |
The name of the user who made the topic. |
Post Responses
| Field |
Type |
Description |
author |
String |
The post's author. |
avatar |
String |
The URL of the author's avatar. May be a link to the CDN path, or a data: URI. |
body |
String |
The post text. |
created_at |
RFC3339 datetime |
The creation time, in UTC, of the post. |
edit_reason |
String |
The edit reason for this post. |
edited_at |
RFC3339 datetime |
The time, in UTC, this post was last edited at, or null if it was not edited. |
id |
Integer |
The post's ID (used to identify it). |
updated_at |
RFC3339 datetime |
The time, in UTC, the post was last updated at. |
user_id |
Integer |
The ID of the user the post 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_uri |
String |
The spoiler image for the tag. |
User Responses
| Field |
Type |
Description |
id |
Integer |
The ID of the user. |
name |
String |
The name of the user. |
slug |
String |
The slug of the user. |
role |
String |
The role of the user. |
description |
String |
The description (bio) of the user. |
avatar_url |
String |
The URL of the user's thumbnail. null if the avatar is not set. |
created_at |
RFC3339 datetime |
The creation time, in UTC, of the user. |
comments_count |
Integer |
The comment count of the user. |
uploads_count |
Integer |
The upload count of the user. |
posts_count |
Integer |
The forum posts count of the user. |
topics_count |
Integer |
The forum topics count of the user. |
links |
Object |
The links the user has registered. See links-response. |
awards |
Object |
The awards/badges of the user. See awards-response. |
Filter Responses
| Field |
Type |
Description |
id |
Integer |
The id of the filter. |
name |
String |
The name of the filter. |
description |
String |
The description of the filter. |
user_id |
Integer |
The id of the user the filter belongs to. null if it isn't assigned to a user (usually system filters only). |
user_count |
Integer |
The amount of users employing this filter. |
system |
Boolean |
If true, is a system filter. System filters are usable by anyone and don't have a user_id set. |
public |
Boolean |
If true, is a public filter. Public filters are usable by anyone. |
spoilered_tag_ids |
Array |
A list of tag IDs (as integers) that this filter will spoil. |
spoilered_complex |
String |
The complex spoiled filter. |
hidden_tag_ids |
Array |
A list of tag IDs (as integers) that this filter will hide. |
hidden_complex |
String |
The complex hidden filter. |
Links Responses
| Field |
Type |
Description |
user_id |
Integer |
The ID of the user who owns this link. |
created_at |
RFC3339 datetime |
The creation time, in UTC, of this link. |
state |
String |
The state of this link. |
tag_id |
Integer |
The ID of an associated tag for this link. null if no tag linked. |
Awards Responses
| Field |
Type |
Description |
image_url |
String |
The URL of this award. |
title |
String |
The title of this award. |
id |
Integer |
The ID of the badge this award is derived from. |
label |
String |
The label of this award. |
awarded_on |
RFC3339 datetime |
The time, in UTC, when this award was given. |
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. |
Image Errors Responses
Each field is optional and is an Array of Strings.
| Field |
Type |
Description |
image |
Array |
Errors in the submitted image |
image_aspect_ratio |
Array |
Errors in the submitted image |
image_format |
Array |
When an image is unsupported (ex. WEBP) |
image_height |
Array |
Errors in the submitted image |
image_width |
Array |
Errors in the submitted image |
image_size |
Array |
Usually if an image that is too large is uploaded. |
image_is_animated |
Array |
Errors in the submitted image |
image_mime_type |
Array |
Errors in the submitted image |
image_orig_sha512_hash |
Array |
Errors in the submitted image. If has already been taken is present, means the image already exists in the database. |
image_sha512_hash |
Array |
Errors in the submitted image |
tag_input |
Array |
Errors with the tag metadata. |
uploaded_image |
Array |
Errors in the submitted image |
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. |
ponybooru_comments |
Integer |
The number of comments made on the image. |
ponybooru_id |
Integer |
The image's ID. |
ponybooru_score |
Integer |
The image's number of upvotes minus the image's number of downvotes. |
ponybooru_tags |
Array |
The names of the image's tags. |
provider_name |
String |
Always "Ponybooru". |
provider_url |
String |
Always "https://ponybooru.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". |
