<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/images</code></td>
<td><code>key, url</code></td>
<td>Submits a new image. Both <code>key</code> and <code>url</code> are required. Errors will result in an <code>{"errors":<a href="#image-errors-response">image-errors-response</a>}</code>.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="#posting-images">Posting images</a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/system</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>filter responses</em> that are flagged as being <em>system</em> filters (and thus usable by anyone).</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/system"><code>/api/v1/json/filters/system</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/user</code></td>
<td><code>key, page</code></td>
<td>Fetches a list of <em>filter responses</em> that belong to the user given by <em>key</em>. If no <em>key</em> is given or it is invalid, will return a <em>403 Forbidden</em> error.</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/user"><code>/api/v1/json/filters/user</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="posting-images">Posting Images</h2>
<p>Posting images should be done via request body parameters. An example with all parameters included is shown below.</p>
<p>You are <em>strongly recommended</em> to test code using this endpoint using a local copy of the website's source code. Abuse of the endpoint <strong>will result in a ban</strong>.</p>
<p>You <em>must</em> provide the direct link to the image in the <code>url</code> parameter.</p>
<p>You <em>must</em> set the <code>content-type</code> header to <code>application/json</code> for the site to process your request.</p>
<pre>POST /api/v1/json/images?key=API_KEY</pre>
<pre class="literal">{
"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, derpibooru 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://derpibooru.org/images/0"
},
"url": "https://derpicdn.net/img/view/2012/1/2/0.jpg"
}</pre>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>animated</code></td>
<td>Boolean</td>
<td>Whether the image is animated.</td>
</tr>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>duration</code></td>
<td>Float</td>
<td>The number of seconds the image lasts, if animated, otherwise .04.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of the image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether the image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that the image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of the image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>size</code></td>
<td>Integer</td>
<td>The number of bytes the image's file contains.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>(Deprecated - Use <code>source_urls</code> field instead) Provides the first source URL of the image as stored in the database, intended for legacy applications only.</td>
</tr>
<tr>
<td><code>source_urls</code></td>
<td>String[]</td>
<td>A list of all source URLs provided for the image, may be empty.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether the image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on the image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs the image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names the image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether the image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader. <code>null</code> if uploaded anonymously.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the comment.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this comment, or <code>null</code> if none provided.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this comment was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the comment was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the post.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this post.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this post was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the post was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the post belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image_uri</code></td>
<td>String</td>
<td>The spoiler image for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>null</code> if the avatar is not set.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="image-errors-response">Image Errors Responses</h2>
<p>Each field is optional and is an <code>Array</code> of <code>String</code>s.</p>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_aspect_ratio</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_format</code></td>
<td>Array</td>
<td>When an image is unsupported (ex. WEBP)</td>
</tr>
<tr>
<td><code>image_height</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_width</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_size</code></td>
<td>Array</td>
<td>Usually if an image that is too large is uploaded.</td>
</tr>
<tr>
<td><code>image_is_animated</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_mime_type</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_orig_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image. If <em>has already been taken</em> is present, means the image already exists in the database.</td>
</tr>
<tr>
<td><code>image_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>tag_input</code></td>
<td>Array</td>
<td>Errors with the tag metadata.</td>
</tr>
<tr>
<td><code>uploaded_image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/images</code></td>
<td><code>key, url</code></td>
<td>Submits a new image. Both <code>key</code> and <code>url</code> are required. Errors will result in an <code>{"errors":<a href="#image-errors-response">image-errors-response</a>}</code>.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="#posting-images">Posting images</a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/system</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>filter responses</em> that are flagged as being <em>system</em> filters (and thus usable by anyone).</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/system"><code>/api/v1/json/filters/system</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/user</code></td>
<td><code>key, page</code></td>
<td>Fetches a list of <em>filter responses</em> that belong to the user given by <em>key</em>. If no <em>key</em> is given or it is invalid, will return a <em>403 Forbidden</em> error.</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/user"><code>/api/v1/json/filters/user</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="posting-images">Posting Images</h2>
<p>Posting images should be done via request body parameters. An example with all parameters included is shown below.</p>
<p>You are <em>strongly recommended</em> to test code using this endpoint using a local copy of the website's source code. Abuse of the endpoint <strong>will result in a ban</strong>.</p>
<p>You <em>must</em> provide the direct link to the image in the <code>url</code> parameter.</p>
<p>You <em>must</em> set the <code>content-type</code> header to <code>application/json</code> for the site to process your request.</p>
<pre>POST /api/v1/json/images?key=API_KEY</pre>
<pre class="literal">{
"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, derpibooru 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://derpibooru.org/images/0"
},
"url": "https://derpicdn.net/img/view/2012/1/2/0.jpg"
}</pre>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>animated</code></td>
<td>Boolean</td>
<td>Whether the image is animated.</td>
</tr>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>duration</code></td>
<td>Float</td>
<td>The number of seconds the image lasts, if animated, otherwise .04.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of the image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether the image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that the image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of the image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>size</code></td>
<td>Integer</td>
<td>The number of bytes the image's file contains.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
<td>(Deprecated - Use <code>source_urls</code> field instead) Provides the first source URL of the image as stored in the database, intended for legacy applications only.</td>
</tr>
<tr>
<td><code>source_urls</code></td>
<td>String[]</td>
<td>A list of all source URLs provided for the image, may be empty.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether the image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on the image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs the image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names the image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether the image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader. <code>null</code> if uploaded anonymously.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the comment.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this comment, or <code>null</code> if none provided.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this comment was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the comment was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the post.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this post.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this post was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the post was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the post belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image_uri</code></td>
<td>String</td>
<td>The spoiler image for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>null</code> if the avatar is not set.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="image-errors-response">Image Errors Responses</h2>
<p>Each field is optional and is an <code>Array</code> of <code>String</code>s.</p>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_aspect_ratio</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_format</code></td>
<td>Array</td>
<td>When an image is unsupported (ex. WEBP)</td>
</tr>
<tr>
<td><code>image_height</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_width</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_size</code></td>
<td>Array</td>
<td>Usually if an image that is too large is uploaded.</td>
</tr>
<tr>
<td><code>image_is_animated</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_mime_type</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_orig_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image. If <em>has already been taken</em> is present, means the image already exists in the database.</td>
</tr>
<tr>
<td><code>image_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>tag_input</code></td>
<td>Array</td>
<td>Errors with the tag metadata.</td>
</tr>
<tr>
<td><code>uploaded_image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/images</code></td>
<td><code>key, url</code></td>
<td>Submits a new image. Both <code>key</code> and <code>url</code> are required. Errors will result in an <code>{"errors":<a href="#image-errors-response">image-errors-response</a>}</code>.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="#posting-images">Posting images</a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/system</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>filter responses</em> that are flagged as being <em>system</em> filters (and thus usable by anyone).</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/system"><code>/api/v1/json/filters/system</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/user</code></td>
<td><code>key, page</code></td>
<td>Fetches a list of <em>filter responses</em> that belong to the user given by <em>key</em>. If no <em>key</em> is given or it is invalid, will return a <em>403 Forbidden</em> error.</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/user"><code>/api/v1/json/filters/user</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="posting-images">Posting Images</h2>
<p>Posting images should be done via request body parameters. An example with all parameters included is shown below.</p>
<p>You are <em>strongly recommended</em> to test code using this endpoint using a local copy of the website's source code. Abuse of the endpoint <strong>will result in a ban</strong>.</p>
<p>You <em>must</em> provide the direct link to the image in the <code>url</code> parameter.</p>
<p>You <em>must</em> set the <code>content-type</code> header to <code>application/json</code> for the site to process your request.</p>
<pre>POST /api/v1/json/images?key=API_KEY</pre>
<pre class="literal">{
"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, derpibooru 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://derpibooru.org/images/0"
},
"url": "https://derpicdn.net/img/view/2012/1/2/0.jpg"
}</pre>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>animated</code></td>
<td>Boolean</td>
<td>Whether the image is animated.</td>
</tr>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>duration</code></td>
<td>Float</td>
<td>The number of seconds the image lasts, if animated.</td>
<td>The number of seconds the image lasts, if animated, otherwise .04.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of the image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether the image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that the image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of the image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>size</code></td>
<td>Integer</td>
<td>The number of bytes the image's file contains.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether the image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on the image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs the image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names the image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether the image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader. <code>null</code> if uploaded anonymously.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the comment.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this comment, or <code>null</code> if none provided.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this comment was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the comment was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the post.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this post.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this post was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the post was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the post belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image_uri</code></td>
<td>String</td>
<td>The spoiler image for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>null</code> if the avatar is not set.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="image-errors-response">Image Errors Responses</h2>
<p>Each field is optional and is an <code>Array</code> of <code>String</code>s.</p>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_aspect_ratio</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_format</code></td>
<td>Array</td>
<td>When an image is unsupported (ex. WEBP)</td>
</tr>
<tr>
<td><code>image_height</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_width</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_size</code></td>
<td>Array</td>
<td>Usually if an image that is too large is uploaded.</td>
</tr>
<tr>
<td><code>image_is_animated</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_mime_type</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_orig_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image. If <em>has already been taken</em> is present, means the image already exists in the database.</td>
</tr>
<tr>
<td><code>image_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>tag_input</code></td>
<td>Array</td>
<td>Errors with the tag metadata.</td>
</tr>
<tr>
<td><code>uploaded_image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/images</code></td>
<td><code>key, url</code></td>
<td>Submits a new image. Both <code>key</code> and <code>url</code> are required. Errors will result in an <code>{"errors":<a href="#image-errors-response">image-errors-response</a>}</code>.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="#posting-images">Posting images</a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/system</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>filter responses</em> that are flagged as being <em>system</em> filters (and thus usable by anyone).</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/system"><code>/api/v1/json/filters/system</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/user</code></td>
<td><code>key, page</code></td>
<td>Fetches a list of <em>filter responses</em> that belong to the user given by <em>key</em>. If no <em>key</em> is given or it is invalid, will return a <em>403 Forbidden</em> error.</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/user"><code>/api/v1/json/filters/user</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="posting-images">Posting Images</h2>
<p>Posting images should be done via request body parameters. An example with all parameters included is shown below.</p>
<p>You are <em>strongly recommended</em> to test code using this endpoint using a local copy of the website's source code. Abuse of the endpoint <strong>will result in a ban</strong>.</p>
<p>You <em>must</em> provide the direct link to the image in the <code>url</code> parameter.</p>
<p>You <em>must</em> set the <code>content-type</code> header to <code>application/json</code> for the site to process your request.</p>
<pre>POST /api/v1/json/images?key=API_KEY</pre>
<pre class="literal">{
"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, derpibooru 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://derpibooru.org/images/0"
},
"url": "https://derpicdn.net/img/view/2012/1/2/0.jpg"
}</pre>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>animated</code></td>
<td>Boolean</td>
<td>Whether the image is animated.</td>
</tr>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>duration</code></td>
<td>Float</td>
<td>The number of seconds the image lasts, if animated.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
<td>The time, in UTC, the image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
<td>The file extension of the image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
<td>Whether the image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
<td>The filename that the image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
<td>The SHA512 hash of the image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>size</code></td>
<td>Integer</td>
<td>The number of bytes the image's file contains.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
<td>Whether the image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
<td>The number of tags present on the image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
<td>A list of tag IDs the image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
<td>A list of tag names the image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
<td>Whether the image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader. <code>null</code> if uploaded anonymously.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the comment.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this comment, or <code>null</code> if none provided.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this comment was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the comment was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the post.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this post.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this post was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the post was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the post belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image_uri</code></td>
<td>String</td>
<td>The spoiler image for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>null</code> if the avatar is not set.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="image-errors-response">Image Errors Responses</h2>
<p>Each field is optional and is an <code>Array</code> of <code>String</code>s.</p>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_aspect_ratio</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_format</code></td>
<td>Array</td>
<td>When an image is unsupported (ex. WEBP)</td>
</tr>
<tr>
<td><code>image_height</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_width</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_size</code></td>
<td>Array</td>
<td>Usually if an image that is too large is uploaded.</td>
</tr>
<tr>
<td><code>image_is_animated</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_mime_type</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_orig_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image. If <em>has already been taken</em> is present, means the image already exists in the database.</td>
</tr>
<tr>
<td><code>image_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>tag_input</code></td>
<td>Array</td>
<td>Errors with the tag metadata.</td>
</tr>
<tr>
<td><code>uploaded_image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/images</code></td>
<td><code>key, url</code></td>
<td>Submits a new image. Both <code>key</code> and <code>url</code> are required. Errors will result in an <code>{"errors":<a href="#image-errors-response">image-errors-response</a>}</code>.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="#posting-images">Posting images</a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/system</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>filter responses</em> that are flagged as being <em>system</em> filters (and thus usable by anyone).</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/system"><code>/api/v1/json/filters/system</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/user</code></td>
<td><code>key, page</code></td>
<td>Fetches a list of <em>filter responses</em> that belong to the user given by <em>key</em>. If no <em>key</em> is given or it is invalid, will return a <em>403 Forbidden</em> error.</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/user"><code>/api/v1/json/filters/user</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="posting-images">Posting Images</h2>
<p>Posting images should be done via request body parameters. An example with all parameters included is shown below.</p>
<p>You are <em>strongly recommended</em> to test code using this endpoint using a local copy of the website's source code. Abuse of the endpoint <strong>will result in a ban</strong>.</p>
<p>You <em>must</em> provide the direct link to the image in the <code>url</code> parameter.</p>
<p>You <em>must</em> set the <code>content-type</code> header to <code>application/json</code> for the site to process your request.</p>
<pre>POST /api/v1/json/images?key=API_KEY</pre>
<pre class="literal">{
"image": {
"description": "[bq]Hypothetically speaking... \n\n\"[Ko-Fi]\":https://ko-fi.com/dilarus \"[Patreon]\":https://www.patreon.com/Dilarus_art \"[Twitter]\":https://twitter.com/Dilarus\n[/bq]\nHigh-quality art posted with permission of artist.\n",
"tag_input": "safe, artist:dilarus, pinkie pie, twilight sparkle, alicorn, earth pony, pony, ..., dialogue, female, hug, lesbian, mare, monochrome, shipping, simple background, traditional art, twilight sparkle (alicorn), twinkie, white background",
"source_url": "https://twitter.com/Dilarus/status/1255968549052583941"
"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, derpibooru 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://derpibooru.org/images/0"
},
"url": "https://pbs.twimg.com/media/EW4YtdmWAAEPaae.png:orig"
"url": "https://derpicdn.net/img/view/2012/1/2/0.jpg"
}</pre>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader. <code>null</code> if uploaded anonymously.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the comment.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this comment, or <code>null</code> if none provided.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this comment was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the comment was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the post.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this post.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this post was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the post was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the post belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image_uri</code></td>
<td>String</td>
<td>The spoiler image for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>null</code> if the avatar is not set.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="image-errors-response">Image Errors Responses</h2>
<p>Each field is optional and is an <code>Array</code> of <code>String</code>s.</p>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_aspect_ratio</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_format</code></td>
<td>Array</td>
<td>When an image is unsupported (ex. WEBP)</td>
</tr>
<tr>
<td><code>image_height</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_width</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_size</code></td>
<td>Array</td>
<td>Usually if an image that is too large is uploaded.</td>
</tr>
<tr>
<td><code>image_is_animated</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_mime_type</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_orig_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image. If <em>has already been taken</em> is present, means the image already exists in the database.</td>
</tr>
<tr>
<td><code>image_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>tag_input</code></td>
<td>Array</td>
<td>Errors with the tag metadata.</td>
</tr>
<tr>
<td><code>uploaded_image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/images</code></td>
<td><code>key, url</code></td>
<td>Submits a new image. Both <code>key</code> and <code>url</code> are required. Errors will result in an <code>{"errors":<a href="#image-errors-response">image-errors-response</a>}</code>.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="#posting-images">Posting images</a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/system</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>filter responses</em> that are flagged as being <em>system</em> filters (and thus usable by anyone).</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/system"><code>/api/v1/json/filters/system</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/user</code></td>
<td><code>key, page</code></td>
<td>Fetches a list of <em>filter responses</em> that belong to the user given by <em>key</em>. If no <em>key</em> is given or it is invalid, will return a <em>403 Forbidden</em> error.</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/user"><code>/api/v1/json/filters/user</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="posting-images">Posting Images</h2>
<p>Posting images should be done via request body parameters. An example with all parameters included is shown below.</p>
<p>You are <em>strongly recommended</em> to test code using this endpoint using a local copy of the website's source code. Abuse of the endpoint <strong>will result in a ban</strong>.</p>
<p>You <em>must</em> provide the direct link to the image in the <code>url</code> parameter.</p>
<p>You <em>must</em> set the <code>content-type</code> header to <code>application/json</code> for the site to process your request.</p>
<pre>POST /api/v1/json/images?key=API_KEY</pre>
<pre class="literal">{
"image": {
"description": "[bq]Hypothetically speaking... \n\n\"[Ko-Fi]\":https://ko-fi.com/dilarus \"[Patreon]\":https://www.patreon.com/Dilarus_art \"[Twitter]\":https://twitter.com/Dilarus\n[/bq]\nHigh-quality art posted with permission of artist.\n",
"tag_input": "safe, artist:dilarus, pinkie pie, twilight sparkle, alicorn, earth pony, pony, ..., dialogue, female, hug, lesbian, mare, monochrome, shipping, simple background, traditional art, twilight sparkle (alicorn), twinkie, white background",
"source_url": "https://twitter.com/Dilarus/status/1255968549052583941"
},
"url": "https://pbs.twimg.com/media/EW4YtdmWAAEPaae.png:orig"
}</pre>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader. <code>Null</code> if uploaded anonymously.</td>
<td>The ID of the image's uploader. <code>null</code> if uploaded anonymously.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the comment.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this comment, or <code>null</code> if none provided.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this comment was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the comment was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>Null</code> if posted anonymously.</td>
<td>The ID of the user who made the topic. <code>null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the post.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this post.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this post was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the post was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the post belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image_uri</code></td>
<td>String</td>
<td>The spoiler image for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>Null</code> if they haven't set one.</td>
<td>The URL of the user's thumbnail. <code>null</code> if the avatar is not set.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>Null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
<td>The id of the user the filter belongs to. <code>null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>Null</code> if no tag linked.</td>
<td>The ID of an associated tag for this link. <code>null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="image-errors-response">Image Errors Responses</h2>
<p>Each field is optional and is an <code>Array</code> of <code>String</code>s.</p>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_aspect_ratio</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_format</code></td>
<td>Array</td>
<td>When an image is unsupported (ex. WEBP)</td>
</tr>
<tr>
<td><code>image_height</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_width</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_size</code></td>
<td>Array</td>
<td>Usually if an image that is too large is uploaded.</td>
</tr>
<tr>
<td><code>image_is_animated</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_mime_type</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_orig_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image. If <em>has already been taken</em> is present, means the image already exists in the database.</td>
</tr>
<tr>
<td><code>image_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>tag_input</code></td>
<td>Array</td>
<td>Errors with the tag metadata.</td>
</tr>
<tr>
<td><code>uploaded_image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/images</code></td>
<td><code>key, url</code></td>
<td>Submits a new image. Both <code>key</code> and <code>url</code> are required. Errors will result in an <code>{"errors":<a href="#image-errors-response">image-errors-response</a>}</code>.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="#posting-images">Posting images</a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/system</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>filter responses</em> that are flagged as being <em>system</em> filters (and thus usable by anyone).</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/system"><code>/api/v1/json/filters/system</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/user</code></td>
<td><code>key, page</code></td>
<td>Fetches a list of <em>filter responses</em> that belong to the user given by <em>key</em>. If no <em>key</em> is given or it is invalid, will return a <em>403 Forbidden</em> error.</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/user"><code>/api/v1/json/filters/user</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="posting-images">Posting Images</h2>
<p>Posting images should be done via request body parameters. An example with all parameters included is shown below.</p>
<p>You are <em>strongly recommended</em> to test code using this endpoint using a local copy of the website's source code. Abuse of the endpoint <strong>will result in a ban</strong>.</p>
<p>You <em>must</em> provide the direct link to the image in the <code>url</code> parameter.</p>
<p>You <em>must</em> set the <code>content-type</code> header to <code>application/json</code> for the site to process your request.</p>
<pre>POST /api/v1/json/images?key=API_KEY</pre>
<pre class="literal">{
"image": {
"description": "[bq]Hypothetically speaking... \n\n\"[Ko-Fi]\":https://ko-fi.com/dilarus \"[Patreon]\":https://www.patreon.com/Dilarus_art \"[Twitter]\":https://twitter.com/Dilarus\n[/bq]\nHigh-quality art posted with permission of artist.\n",
"tag_input": "safe, artist:dilarus, pinkie pie, twilight sparkle, alicorn, earth pony, pony, ..., dialogue, female, hug, lesbian, mare, monochrome, shipping, simple background, traditional art, twilight sparkle (alicorn), twinkie, white background",
"source_url": "https://twitter.com/Dilarus/status/1255968549052583941"
},
"url": "https://pbs.twimg.com/media/EW4YtdmWAAEPaae.png:orig"
}</pre>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
<td>The ID of the image's uploader. <code>Null</code> if uploaded anonymously.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the comment.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this comment, or <code>null</code> if none provided.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this comment was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 dateime</td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the comment was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>Null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the post.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this post.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this post was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 dateime</td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the post was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the post belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image_uri</code></td>
<td>String</td>
<td>The spoiler image for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>Null</code> if they haven't set one.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>Null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>Null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="image-errors-response">Image Errors Responses</h2>
<p>Each field is optional and is an <code>Array</code> of <code>String</code>s.</p>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_aspect_ratio</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_format</code></td>
<td>Array</td>
<td>When an image is unsupported (ex. WEBP)</td>
</tr>
<tr>
<td><code>image_height</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_width</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_size</code></td>
<td>Array</td>
<td>Usually if an image that is too large is uploaded.</td>
</tr>
<tr>
<td><code>image_is_animated</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_mime_type</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_orig_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image. If <em>has already been taken</em> is present, means the image already exists in the database.</td>
</tr>
<tr>
<td><code>image_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>tag_input</code></td>
<td>Array</td>
<td>Errors with the tag metadata.</td>
</tr>
<tr>
<td><code>uploaded_image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/images</code></td>
<td><code>key, url</code></td>
<td>Submits a new image. Both <code>key</code> and <code>url</code> are required. Errors will result in an <code>{"errors":<a href="#image-errors-response">image-errors-response</a>}</code>.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="#posting-images">Posting images</a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/system</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>filter responses</em> that are flagged as being <em>system</em> filters (and thus usable by anyone).</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/system"><code>/api/v1/json/filters/system</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/user</code></td>
<td><code>key, page</code></td>
<td>Fetches a list of <em>filter responses</em> that belong to the user given by <em>key</em>. If no <em>key</em> is given or it is invalid, will return a <em>403 Forbidden</em> error.</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/user"><code>/api/v1/json/filters/user</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="posting-images">Posting Images</h2>
<p>Posting images should be done via request body parameters. An example with all parameters included is shown below.</p>
<p>You are <em>strongly recommended</em> to test code using this endpoint using a local copy of the website's source code. Abuse of the endpoint <strong>will result in a ban</strong>.</p>
<p>You <em>must</em> provide the direct link to the image in the <code>url</code> parameter.</p>
<p>You <em>must</em> set the <code>content-type</code> header to <code>application/json</code> for the site to process your request.</p>
<pre>POST /api/v1/json/images?key=API_KEY</pre>
<pre class="literal">{
"image": {
"description": "[bq]Hypothetically speaking... \n\n\"[Ko-Fi]\":https://ko-fi.com/dilarus \"[Patreon]\":https://www.patreon.com/Dilarus_art \"[Twitter]\":https://twitter.com/Dilarus\n[/bq]\nHigh-quality art posted with permission of artist.\n",
"tag_input": "safe, artist:dilarus, pinkie pie, twilight sparkle, alicorn, earth pony, pony, ..., dialogue, female, hug, lesbian, mare, monochrome, shipping, simple background, traditional art, twilight sparkle (alicorn), twinkie, white background",
"source_url": "https://twitter.com/Dilarus/status/1255968549052583941"
},
"url": "https://pbs.twimg.com/media/EW4YtdmWAAEPaae.png:orig"
}</pre>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the comment.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this comment, or <code>null</code> if none provided.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this comment was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 dateime</td>
<td>The time, in UTC, the comment was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>Null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the post.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this post.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this post was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 dateime</td>
<td>The time, in UTC, the post was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the post belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image_uri</code></td>
<td>String</td>
<td>The spoiler image for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>Null</code> if they haven't set one.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>Null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>Null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="image-errors-response">Image Errors Responses</h2>
<p>Each field is optional and is an <code>Array</code> of <code>String</code>s.</p>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_aspect_ratio</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_format</code></td>
<td>Array</td>
<td>When an image is unsupported (ex. WEBP)</td>
</tr>
<tr>
<td><code>image_height</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_width</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_size</code></td>
<td>Array</td>
<td>Usually if an image that is too large is uploaded.</td>
</tr>
<tr>
<td><code>image_is_animated</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_mime_type</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>image_orig_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image. If <em>has already been taken</em> is present, means the image already exists in the database.</td>
</tr>
<tr>
<td><code>image_sha512_hash</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
<tr>
<td><code>tag_input</code></td>
<td>Array</td>
<td>Errors with the tag metadata.</td>
</tr>
<tr>
<td><code>uploaded_image</code></td>
<td>Array</td>
<td>Errors in the submitted image</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/system</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>filter responses</em> that are flagged as being <em>system</em> filters (and thus usable by anyone).</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/system"><code>/api/v1/json/filters/system</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/user</code></td>
<td><code>key, page</code></td>
<td>Fetches a list of <em>filter responses</em> that belong to the user given by <em>key</em>. If no <em>key</em> is given or it is invalid, will return a <em>403 Forbidden</em> error.</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/user"><code>/api/v1/json/filters/user</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the comment.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this comment, or <code>null</code> if none provided.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this comment was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 dateime</td>
<td>The time, in UTC, the comment was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>Null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the post.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this post.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this post was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 dateime</td>
<td>The time, in UTC, the post was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the post belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td><code>spoiler_image_uri</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
<td>The spoiler image for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>Null</code> if they haven't set one.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>Null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>Null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/system</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>filter responses</em> that are flagged as being <em>system</em> filters (and thus usable by anyone).</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/system"><code>/api/v1/json/filters/system</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/user</code></td>
<td><code>key, page</code></td>
<td>Fetches a list of <em>filter responses</em> that belong to the user given by <em>key</em>. If no <em>key</em> is given or it is invalid, will return a <em>403 Forbidden</em> error.</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/user"><code>/api/v1/json/filters/user</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the comment.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this comment, or <code>null</code> if none provided.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this comment was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 dateime</td>
<td>The time, in UTC, the comment was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>Null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>avatar</code></td>
<td>String</td>
<td>The URL of the author's avatar. May be a link to the CDN path, or a <code>data:</code> URI.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the post.</td>
</tr>
<tr>
<td><code>edit_reason</code></td>
<td>String</td>
<td>The edit reason for this post.</td>
</tr>
<tr>
<td><code>edited_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this post was last edited at, or <code>null</code> if it was not edited.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 dateime</td>
<td>The time, in UTC, the post was last updated at.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
<td>The ID of the user the post belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>Null</code> if they haven't set one.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>Null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>Null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/system</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>filter responses</em> that are flagged as being <em>system</em> filters (and thus usable by anyone).</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/system"><code>/api/v1/json/filters/system</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/user</code></td>
<td><code>key, page</code></td>
<td>Fetches a list of <em>filter responses</em> that belong to the user given by <em>key</em>. If no <em>key</em> is given or it is invalid, will return a <em>403 Forbidden</em> error.</td>
<td><code>{"filters":[<a href="#filter-response">filter-response</a>]}</code></td>
<td><a href="/api/v1/json/filters/user"><code>/api/v1/json/filters/user</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>Null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>Null</code> if they haven't set one.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>Null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>Null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/filters/:filter_id</code></td>
<td><code>key</code></td>
<td>Fetches a <em>filter response</em> for the filter ID given by the <code>filter_id</code> URL parameter.</td>
<td><code>{"filter":<a href="#filter-response">filter-response</a>}</code></td>
<td><a href="/api/v1/json/filters/56027"><code>/api/v1/json/filters/56027</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>Null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>Null</code> if they haven't set one.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the. See <a href="#awards-response">awards-response</a>.</td>
<td>The awards/badges of the user. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="filter-response">Filter Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The id of the filter.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the filter.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description of the filter.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The id of the user the filter belongs to. <code>Null</code> if it isn't assigned to a user (usually <code>system</code> filters only).</td>
</tr>
<tr>
<td><code>user_count</code></td>
<td>Integer</td>
<td>The amount of users employing this filter.</td>
</tr>
<tr>
<td><code>system</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a system filter. System filters are usable by anyone and don't have a <code>user_id</code> set.</td>
</tr>
<tr>
<td><code>public</code></td>
<td>Boolean</td>
<td>If <code>true</code>, is a public filter. Public filters are usable by anyone.</td>
</tr>
<tr>
<td><code>spoilered_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will spoil.</td>
</tr>
<tr>
<td><code>spoilered_complex</code></td>
<td>String</td>
<td>The complex spoiled filter.</td>
</tr>
<tr>
<td><code>hidden_tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs (as integers) that this filter will hide.</td>
</tr>
<tr>
<td><code>hidden_complex</code></td>
<td>String</td>
<td>The complex hidden filter.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>Null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "png", "svg", "webm"</code>.</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "jpeg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>Null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>Null</code> if they haven't set one.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>Null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/featured</code></td>
<td><code></code></td>
<td>Fetches an <em>image response</em> for the for the current featured image.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/featured"><code>/api/v1/json/images/featured</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code></code></td>
<td>Fetches a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/posts/:post_id</code></td>
<td><code></code></td>
<td>Fetches a <em>post response</em> for the post ID given by the <code>post_id</code> URL parameter.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/posts/2730144"><code>/api/v1/json/posts/2730144</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/profiles/:user_id</code></td>
<td><code></code></td>
<td>Fetches a <em>profile response</em> for the user ID given by the <code>user_id</code> URL parameter.</td>
<td><code>{"user":<a href="#user-response">user-response</a>}</code></td>
<td><a href="/api/v1/json/profiles/216494"><code>/api/v1/json/profiles/216494</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Returns an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td>Fetches an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url</code></td>
<td><code>key, url, distance</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code>key</code></td>
<td>Returns a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
<td><code>/api/v1/json/forums</code></td>
<td></td>
<td>Fetches a list of <em>forum responses</em>.</td>
<td><code>{"forums":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums"><code>/api/v1/json/forums</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name</code></td>
<td></td>
<td>Fetches a <em>forum response</em> for the abbreviated name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"forum":<a href="#forum-response">forum-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis"><code>/api/v1/json/forums/dis</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>topic responses</em> for the abbreviated forum name given by the <code>short_name</code> URL parameter.</td>
<td><code>{"topics":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics"><code>/api/v1/json/forums/dis/topics</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug</code></td>
<td></td>
<td>Fetches a <em>topic response</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"topic":<a href="#topic-response">topic-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts</code></td>
<td><code>page</code></td>
<td>Fetches a list of <em>post responses</em> for the abbreviated forum name given by the <code>short_name</code> and topic given by <code>topic_slug</code> URL parameters.</td>
<td><code>{"posts":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/forums/:short_name/topics/:topic_slug/posts/:post_id</code></td>
<td></td>
<td>Fetches a <em>post response</em> for the abbreviated forum name given by the <code>short_name</code>, topic given by <code>topic_slug</code> and post given by <code>post_id</code> URL parameters.</td>
<td><code>{"post":<a href="#post-response">post-response</a>}</code></td>
<td><a href="/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095"><code>/api/v1/json/forums/dis/topics/ask-the-mods-anything/posts/2761095</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="forum-response">Forum Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The forum's name.</td>
</tr>
<tr>
<td><code>short_name</code></td>
<td>String</td>
<td>The forum's short name (used to identify it).</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The forum's description.</td>
</tr>
<tr>
<td><code>topic_count</code></td>
<td>Integer</td>
<td>The amount of topics in the forum.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the forum.</td>
</tr>
</tbody>
</table>
<h2 id="topic-response">Topic Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The topic's slug (used to identify it).</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The topic's title.</td>
</tr>
<tr>
<td><code>post_count</code></td>
<td>Integer</td>
<td>The amount of posts in the topic.</td>
</tr>
<tr>
<td><code>view_count</code></td>
<td>Integer</td>
<td>The amount of views the topic has received.</td>
</tr>
<tr>
<td><code>sticky</code></td>
<td>Boolean</td>
<td>Whether the topic is sticky.</td>
</tr>
<tr>
<td><code>last_replied_to_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when the last reply was made.</td>
</tr>
<tr>
<td><code>locked</code></td>
<td>Boolean</td>
<td>Whether the topic is locked.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who made the topic. <code>Null</code> if posted anonymously.</td>
</tr>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The name of the user who made the topic.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID.</td>
<td>The post's ID (used to identify it).</td>
</tr>
<tr>
<td><code>topic_id</code></td>
<td>Integer</td>
<td>The ID of the topic the post belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="user-response">User Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the user.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug of the user.</td>
</tr>
<tr>
<td><code>role</code></td>
<td>String</td>
<td>The role of the user.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The description (bio) of the user.</td>
</tr>
<tr>
<td><code>avatar_url</code></td>
<td>String</td>
<td>The URL of the user's thumbnail. <code>Null</code> if they haven't set one.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the user.</td>
</tr>
<tr>
<td><code>comments_count</code></td>
<td>Integer</td>
<td>The comment count of the user.</td>
</tr>
<tr>
<td><code>uploads_count</code></td>
<td>Integer</td>
<td>The upload count of the user.</td>
</tr>
<tr>
<td><code>posts_count</code></td>
<td>Integer</td>
<td>The forum posts count of the user.</td>
</tr>
<tr>
<td><code>topics_count</code></td>
<td>Integer</td>
<td>The forum topics count of the user.</td>
</tr>
<tr>
<td><code>links</code></td>
<td>Object</td>
<td>The links the user has registered. See <a href="#links-response">links-response</a>.</td>
</tr>
<tr>
<td><code>awards</code></td>
<td>Object</td>
<td>The awards/badges of the. See <a href="#awards-response">awards-response</a>.</td>
</tr>
</tbody>
</table>
<h2 id="links-response">Links Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user who owns this link.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of this link.</td>
</tr>
<tr>
<td><code>state</code></td>
<td>String</td>
<td>The state of this link.</td>
</tr>
<tr>
<td><code>tag_id</code></td>
<td>Integer</td>
<td>The ID of an associated tag for this link. <code>Null</code> if no tag linked.</td>
</tr>
</tbody>
</table>
<h2 id="awards-response">Awards Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>image_url</code></td>
<td>String</td>
<td>The URL of this award.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The title of this award.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The ID of the badge this award is derived from.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>String</td>
<td>The label of this award.</td>
</tr>
<tr>
<td><code>awarded_on</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, when this award was given.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/comments/:comment_id</code></td>
<td></td>
<td>Fetches a <em>comment response</em> for the comment ID referenced by the <code>comment_id</code> URL parameter.</td>
<td><code>{"comment":<a href="#comment-response">comment-response</a>}</code></td>
<td><a href="/api/v1/json/comments/1000"><code>/api/v1/json/comments/1000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Returns an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code>key</code></td>
<td>Returns a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID.</td>
</tr>
<tr>
<td><code>topic_id</code></td>
<td>Integer</td>
<td>The ID of the topic the post belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Returns an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code>key</code></td>
<td>Returns a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td>hidden_from_users</td>
<td><code>hidden_from_users</code></td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID.</td>
</tr>
<tr>
<td><code>topic_id</code></td>
<td>Integer</td>
<td>The ID of the topic the post belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Returns an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code>key</code></td>
<td>Returns a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>deletion_reason</code></td>
<td>String</td>
<td>The hide reason for the image, or <code>null</code> if none provided. This will only have a value on images which are deleted for a rule violation.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>duplicate_of</code></td>
<td>Integer</td>
<td>The ID of the target image, or <code>null</code> if none provided. This will only have a value on images which are merged into another image.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td>hidden_from_users</td>
<td>Boolean</td>
<td>Whether this image is hidden. An image is hidden if it is merged or deleted for a rule violation.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID.</td>
</tr>
<tr>
<td><code>topic_id</code></td>
<td>Integer</td>
<td>The ID of the topic the post belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Returns an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code>key</code></td>
<td>Returns a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>intensities</code></td>
<td>Object</td>
<td>Optional object of <a href="https://github.com/derpibooru/cli_intensities">internal image intensity data</a> for deduplication purposes. May be <code>null</code> if intensities have not yet been generated.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID.</td>
</tr>
<tr>
<td><code>topic_id</code></td>
<td>Integer</td>
<td>The ID of the topic the post belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Returns an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="imge-response">image-response</a>]}</code></td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code>key</code></td>
<td>Returns a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID.</td>
</tr>
<tr>
<td><code>topic_id</code></td>
<td>Integer</td>
<td>The ID of the topic the post belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, the session may also be read from cookies, and if no cookies are present, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
<td>An optional authentication token. If omitted, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Returns an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="imge-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code>key</code></td>
<td>Returns a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID.</td>
</tr>
<tr>
<td><code>topic_id</code></td>
<td>Integer</td>
<td>The ID of the topic the post belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, the session may also be read from cookies, and if no cookies are present, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Returns an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code>query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code>query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code>query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code>query parameter, and returns <em>image responses</em>.</td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code>query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td>Executes the search given by the <code>q</code> query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="imge-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code>key</code></td>
<td>Returns a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
</tbody>
</table>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID.</td>
</tr>
<tr>
<td><code>topic_id</code></td>
<td>Integer</td>
<td>The ID of the topic the post belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<div class="walloftext">
<p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code>/images/watched.json?key=xxxxxxxxxxxxxxxxxxxx</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><a href="https://github.com/joshua-stone/DerPyBooru">DerPyBooru (Python)</a></li>
<li><a href="https://github.com/Xe/derpigo">derpigo (Go)</a></li>
<li><a href="https://github.com/Ralvke/derpiboorust">derpiboorust (Rust)</a></li>
<li><a href="https://github.com/octet-stream/dinky">dinky.js (JavaScript)</a></li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><a href="/images.json">/images.json</a></li>
<li><a href="/44819.json">/44819.json</a></li>
<li><a href="/search.json?q=pinkie+pie">/search.json?q=pinkie+pie</a></li>
<li><a href="/search.json?q=pinkie+pie&page=2">/search.json?q=pinkie+pie&page=2</a></li>
<li><a href="/search.json?q=first_seen_at.gt:3+days+ago">/search.json?q=first_seen_at.gt:3+days+ago</a></li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument. Fill this in with your personal API key.</p>
<ul>
<li>/images/watched.json?key=xxxxxxxxxxxxxxxxxxxx</li>
<li>/search.json?q=my:faves&key=xxxxxxxxxxxxxxxxxxxx</li>
<li>/search.json?q=my:upvotes&key=xxxxxxxxxxxxxxxxxxxx</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (<code>/images.json</code>)
</h3>
<p>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.</p>
<p>Note that if you are looking to <em>continuously scrape the entire website</em>, we offer <a href="/pages/data_dumps">nightly database dumps</a> instead. Consider if these suit your needs first, then rely on the API if they do not.</p>
<h2 id="licensing">Licensing</h2>
<p>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.</p>
<p>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 <code>https:</code> protocol must be specified on all URLs.</p>
<h2 id="parameters">Parameters</h2>
<p>This is a list of general parameters that are useful when working with the API. Not all parameters may be used in every request.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
<td><code>filter_id</code></td>
<td>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.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
<td><code>key</code></td>
<td>An optional authentication token. If omitted, the session may also be read from cookies, and if no cookies are present, no user will be authenticated.<br/><br/>You can find your authentication token in your <a href="/registration/edit">account settings</a>.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
<td><code>page</code></td>
<td>Controls the current page of the response, if the response is paginated. Empty values default to the first page.</td>
</tr>
<tr>
<td><code>per_page</code></td>
<td>Controls the number of results per page, up to a limit of 50, if the response is paginated. The default is 25.</td>
</tr>
<tr>
<td><code>q</code></td>
<td>The current search query, if the request is a search request.</td>
</tr>
<tr>
<td><code>sd</code></td>
<td>The current sort direction, if the request is a search request.</td>
</tr>
<tr>
<td><code>sf</code></td>
<td>The current sort field, if the request is a search request.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (<code>/search.json</code>)
</h3>
<h2 id="routes">Routes</h2>
<p>The interested reader may find the implementations of these endpoints <a href="https://github.com/derpibooru/philomena/tree/master/lib/philomena_web/controllers/api">here</a>. For the purposes of this document, a brief overview is given.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
<th>Method</th>
<th>Path</th>
<th>Allowed Query Parameters</th>
<th>Description</th>
<th>Response Format</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
<td><code>GET</code></td>
<td><code>/api/v1/json/images/:image_id</code></td>
<td><code>key, filter_id</code></td>
<td>Fetches an <em>image response</em> for the image ID referenced by the <code>image_id</code> URL parameter.</td>
<td><code>{"image":<a href="#image-response">image-response</a>}</code></td>
<td><a href="/api/v1/json/images/1"><code>/api/v1/json/images/1</code></a></td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
<td><code>GET</code></td>
<td><code>/api/v1/json/oembed</code></td>
<td><code>url</code></td>
<td>Returns an <em>oEmbed response</em> for the given app link or CDN URL.</td>
<td><code><a href="#oembed-response">oembed-response</a></code></td>
<td><a href="/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png"><code>/api/v1/json/oembed?url=https://derpicdn.net/img/2012/1/2/3/full.png</code></a></td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and 50).
</td>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/comments</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code>query parameter, and returns <em>comment responses</em> sorted by descending creation time.</td>
<td><code>{"comments":[<a href="#comment-response">comment-response</a>]}</code></td>
<td><a href="/api/v1/json/search/comments?q=image_id:1000000"><code>/api/v1/json/search/comments?q=image_id:1000000</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/galleries</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code>query parameter, and returns <em>gallery responses</em> sorted by descending creation time.</td>
<td><code>{"galleries":[<a href="#gallery-response">gallery-response</a>]}</code></td>
<td><a href="/api/v1/json/search/galleries?q=title:mean*"><code>/api/v1/json/search/galleries?q=title:mean*</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/posts</code></td>
<td><code>key, page</code></td>
<td>Executes the search given by the <code>q</code>query parameter, and returns <em>post responses</em> sorted by descending creation time.</td>
<td><code>{"posts":[<a href="#post-response">post-response</a>]}</code></td>
<td><a href="/api/v1/json/search/posts?q=subject:time wasting thread"><code>/api/v1/json/search/posts?q=subject:time wasting thread</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/images</code></td>
<td><code>key, filter_id, page, per_page, q, sd, sf</code></td>
<td>Executes the search given by the <code>q</code>query parameter, and returns <em>image responses</em>.</td>
<td><code>{"images":[<a href="#image-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/images?q=safe"><code>/api/v1/json/search/images?q=safe</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/search/tags</code></td>
<td><code>page</code></td>
<td>Executes the search given by the <code>q</code>query parameter, and returns <em>tag responses</em> sorted by descending image count.</td>
<td><code>{"tags":[<a href="#tag-response">tag-response</a>]}</code></td>
<td><a href="/api/v1/json/search/tags?q=analyzed_name:wing"><code>/api/v1/json/search/tags?q=analyzed_name:wing</code></a></td>
</tr>
<tr>
<td><code>POST</code></td>
<td><code>/api/v1/json/search/reverse</code></td>
<td><code>key, url</code></td>
<td>Returns <em>image responses</em> based on the results of reverse-searching the image given by the <code>url</code> query parameter.</td>
<td><code>{"images":[<a href="imge-response">image-response</a>]}</code></td>
<td><a href="/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg" data-method="post"><code>/api/v1/json/search/reverse?url=https://derpicdn.net/img/2019/12/24/2228439/full.jpg</code></a></td>
</tr>
<tr>
<td><code>GET</code></td>
<td><code>/api/v1/json/tags/:tag_id</code></td>
<td><code>key</code></td>
<td>Returns a <em>tag response</em> for the <em>tag slug</em> given by the <code>tag_id</code> URL parameter. The tag's ID is <em>not</em> used.</td>
<td><code>{"tag":<a href="#tag-response">tag-response</a>}</code></td>
<td><a href="/api/v1/json/tags/artist-colon-atryl"><code>/api/v1/json/tags/artist-colon-atryl</code></a></td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the oEmbed specification and can be found at
<a href="/oembed.json">/oembed.json</a>
or
<a href="/oembed.xml">/oembed.xml</a>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><a href="/oembed.json?url=https://derpibooru.org/17842">/oembed.json?url=https://derpibooru.org/17842</a></li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
<h2 id="image-response">Image Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aspect_ratio</code></td>
<td>Float</td>
<td>The image's width divided by its height.</td>
</tr>
<tr>
<td><code>comment_count</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>created_at</code></td>
<td>RFC3339 datetime</td>
<td>The creation time, in UTC, of the image.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The image's description.</td>
</tr>
<tr>
<td><code>downvotes</code></td>
<td>Integer</td>
<td>The number of downvotes the image has.</td>
</tr>
<tr>
<td><code>faves</code></td>
<td>Integer</td>
<td>The number of faves the image has.</td>
</tr>
<tr>
<td><code>first_seen_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, this image was first seen (before any duplicate merging).</td>
</tr>
<tr>
<td><code>format</code></td>
<td>String</td>
<td>The file extension of this image. One of <code>"gif", "jpg", "png", "svg", "webm"</code>.</td>
</tr>
<tr>
<td><code>height</code></td>
<td>Integer</td>
<td>The image's height, in pixels.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>mime_type</code></td>
<td>String</td>
<td>The MIME type of this image. One of <code>"image/gif", "image/jpeg", "image/png", "image/svg+xml", "video/webm"</code>.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The filename that this image was uploaded with.</td>
</tr>
<tr>
<td><code>orig_sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image as it was originally uploaded.</td>
</tr>
<tr>
<td><code>processed</code></td>
<td>Boolean</td>
<td>Whether the image has finished optimization.</td>
</tr>
<tr>
<td><code>representations</code></td>
<td>Object</td>
<td>A mapping of representation names to their respective URLs. Contains the keys <code>"full", "large", "medium", "small", "tall", "thumb", "thumb_small", "thumb_tiny"</code>.</td>
</tr>
<tr>
<td><code>score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>sha512_hash</code></td>
<td>String</td>
<td>The SHA512 hash of this image after it has been processed.</td>
</tr>
<tr>
<td><code>source_url</code></td>
<td>String</td>
<td>The current source URL of the image.</td>
</tr>
<tr>
<td><code>spoilered</code></td>
<td>Boolean</td>
<td>Whether this image is hit by the current filter.</td>
</tr>
<tr>
<td><code>tag_count</code></td>
<td>Integer</td>
<td>The number of tags present on this image.</td>
</tr>
<tr>
<td><code>tag_ids</code></td>
<td>Array</td>
<td>A list of tag IDs this image contains.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>Array</td>
<td>A list of tag names this image contains.</td>
</tr>
<tr>
<td><code>thumbnails_generated</code></td>
<td>Boolean</td>
<td>Whether this image has finished thumbnail generation. Do not attempt to load images from <code>view_url</code> or <code>representations</code> if this is false.</td>
</tr>
<tr>
<td><code>updated_at</code></td>
<td>RFC3339 datetime</td>
<td>The time, in UTC, the image was last updated.</td>
</tr>
<tr>
<td><code>uploader</code></td>
<td>String</td>
<td>The image's uploader.</td>
</tr>
<tr>
<td><code>uploader_id</code></td>
<td>Integer</td>
<td>The ID of the image's uploader.</td>
</tr>
<tr>
<td><code>upvotes</code></td>
<td>Integer</td>
<td>The image's number of upvotes.</td>
</tr>
<tr>
<td><code>view_url</code></td>
<td>String</td>
<td>The image's view URL, including tags.</td>
</tr>
<tr>
<td><code>width</code></td>
<td>Integer</td>
<td>The image's width, in pixels.</td>
</tr>
<tr>
<td><code>wilson_score</code></td>
<td>Float</td>
<td>The lower bound of the <a href="https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval">Wilson score interval</a> for the image, based on its upvotes and downvotes, given a z-score corresponding to a confidence of 99.5%.</td>
</tr>
</tbody>
</table>
<h2 id="comment-response">Comment Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The comment's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The comment text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The comment's ID.</td>
</tr>
<tr>
<td><code>image_id</code></td>
<td>Integer</td>
<td>The ID of the image the comment belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="post-response">Post Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author</code></td>
<td>String</td>
<td>The post's author.</td>
</tr>
<tr>
<td><code>body</code></td>
<td>String</td>
<td>The post text.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The post's ID.</td>
</tr>
<tr>
<td><code>topic_id</code></td>
<td>Integer</td>
<td>The ID of the topic the post belongs to.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the user the comment belongs to, if any.</td>
</tr>
</tbody>
</table>
<h2 id="tag-response">Tag Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>aliased_tag</code></td>
<td>String</td>
<td>The slug of the tag this tag is aliased to, if any.</td>
</tr>
<tr>
<td><code>aliases</code></td>
<td>Array</td>
<td>The slugs of the tags aliased to this tag.</td>
</tr>
<tr>
<td><code>category</code></td>
<td>String</td>
<td>The category class of this tag. One of <code>"character", "content-fanmade", "content-official", "error", "oc", "origin", "rating", "species", "spoiler"</code>.</td>
</tr>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The long description for the tag.</td>
</tr>
<tr>
<td><code>dnp_entries</code></td>
<td>Array</td>
<td>An array of objects containing DNP entries claimed on the tag.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The tag's ID.</td>
</tr>
<tr>
<td><code>images</code></td>
<td>Integer</td>
<td>The image count of the tag.</td>
</tr>
<tr>
<td><code>implied_by_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag is implied by.</td>
</tr>
<tr>
<td><code>implied_tags</code></td>
<td>Array</td>
<td>The slugs of the tags this tag implies.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>String</td>
<td>The name of the tag.</td>
</tr>
<tr>
<td><code>name_in_namespace</code></td>
<td>String</td>
<td>The name of the tag in its namespace.</td>
</tr>
<tr>
<td><code>namespace</code></td>
<td>String</td>
<td>The namespace of the tag.</td>
</tr>
<tr>
<td><code>short_description</code></td>
<td>String</td>
<td>The short description for the tag.</td>
</tr>
<tr>
<td><code>slug</code></td>
<td>String</td>
<td>The slug for the tag.</td>
</tr>
<tr>
<td><code>spoiler_image</code></td>
<td>String</td>
<td>The spoiler image URL for the tag.</td>
</tr>
</tbody>
</table>
<h2 id="gallery-response">Gallery Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>description</code></td>
<td>String</td>
<td>The gallery's description.</td>
</tr>
<tr>
<td><code>id</code></td>
<td>Integer</td>
<td>The gallery's ID.</td>
</tr>
<tr>
<td><code>spoiler_warning</code></td>
<td>String</td>
<td>The gallery's spoiler warning.</td>
</tr>
<tr>
<td><code>thumbnail_id</code></td>
<td>Integer</td>
<td>The ID of the cover image for the gallery.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The gallery's title.</td>
</tr>
<tr>
<td><code>user</code></td>
<td>String</td>
<td>The name of the gallery's creator.</td>
</tr>
<tr>
<td><code>user_id</code></td>
<td>Integer</td>
<td>The ID of the gallery's creator.</td>
</tr>
</tbody>
</table>
<h2 id="oembed-response">Oembed Responses</h2>
<table class="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>author_name</code></td>
<td>String</td>
<td>The comma-delimited names of the image authors.</td>
</tr>
<tr>
<td><code>author_url</code></td>
<td>String</td>
<td>The source URL of the image.</td>
</tr>
<tr>
<td><code>cache_age</code></td>
<td>Integer</td>
<td>Always <code>7200</code>.</td>
</tr>
<tr>
<td><code>derpibooru_comments</code></td>
<td>Integer</td>
<td>The number of comments made on the image.</td>
</tr>
<tr>
<td><code>derpibooru_id</code></td>
<td>Integer</td>
<td>The image's ID.</td>
</tr>
<tr>
<td><code>derpibooru_score</code></td>
<td>Integer</td>
<td>The image's number of upvotes minus the image's number of downvotes.</td>
</tr>
<tr>
<td><code>derpibooru_tags</code></td>
<td>Array</td>
<td>The names of the image's tags.</td>
</tr>
<tr>
<td><code>provider_name</code></td>
<td>String</td>
<td>Always <code>"Derpibooru"</code>.</td>
</tr>
<tr>
<td><code>provider_url</code></td>
<td>String</td>
<td>Always <code>"https://derpibooru.org"</code>.</td>
</tr>
<tr>
<td><code>title</code></td>
<td>String</td>
<td>The image's ID and associated tags, as would be given on the title of the image page.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>String</td>
<td>Always <code>"photo"</code>.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>String</td>
<td>Always <code>"1.0"</code>.</td>
</tr>
</tbody>
</table>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpiboorust (Rust)', 'https://github.com/Ralvke/derpiboorust')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'dinky.js (JavaScript)', 'https://github.com/octet-stream/dinky')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/44819.json', '/44819.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/images/44819.json', '/images/44819.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2', '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/lists.json?last=4w', '/lists.json?last=4w')) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and
<%= ::Temple::Utils.escape_html((Booru::CONFIG.settings[:max_images_per_page])) %>
)
</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
<div class="walloftext">
<p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code>/images/watched.json?key=xxxxxxxxxxxxxxxxxxxx</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><a href="https://github.com/joshua-stone/DerPyBooru">DerPyBooru (Python)</a></li>
<li><a href="https://github.com/Xe/derpigo">derpigo (Go)</a></li>
<li><a href="https://github.com/Ralvke/derpiboorust">derpiboorust (Rust)</a></li>
<li><a href="https://github.com/octet-stream/dinky">dinky.js (JavaScript)</a></li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><a href="/images.json">/images.json</a></li>
<li><a href="/44819.json">/44819.json</a></li>
<li><a href="/search.json?q=pinkie+pie">/search.json?q=pinkie+pie</a></li>
<li><a href="/search.json?q=pinkie+pie&page=2">/search.json?q=pinkie+pie&page=2</a></li>
<li><a href="/search.json?q=first_seen_at.gt:3+days+ago">/search.json?q=first_seen_at.gt:3+days+ago</a></li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument. Fill this in with your personal API key.</p>
<ul>
<li>/images/watched.json?key=xxxxxxxxxxxxxxxxxxxx</li>
<li>/search.json?q=my:faves&key=xxxxxxxxxxxxxxxxxxxx</li>
<li>/search.json?q=my:upvotes&key=xxxxxxxxxxxxxxxxxxxx</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (<code>/images.json</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (<code>/search.json</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and 50).
</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the oEmbed specification and can be found at
<a href="/oembed.json">/oembed.json</a>
or
<a href="/oembed.xml">/oembed.xml</a>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><a href="/oembed.json?url=https://derpibooru.org/17842">/oembed.json?url=https://derpibooru.org/17842</a></li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpiboorust (Rust)', 'https://github.com/Ralvke/derpiboorust')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'dinky.js (JavaScript)', 'https://github.com/octet-stream/dinky')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/44819.json', '/44819.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/images/44819.json', '/images/44819.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2', '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/lists.json?last=4w', '/lists.json?last=4w')) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and
<%= ::Temple::Utils.escape_html((Booru::CONFIG.settings[:max_images_per_page])) %>
)
</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpiboorust (Rust)', 'https://github.com/Ralvke/derpiboorust')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'dinky.js (JavaScript)', 'https://github.com/octet-stream/dinky')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json", "/images.json")) %>
<li><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json", "/44819.json")) %>
<li><%= ::Temple::Utils.escape_html((link_to '/44819.json', '/44819.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json", "/images/44819.json")) %>
<li><%= ::Temple::Utils.escape_html((link_to '/images/44819.json', '/images/44819.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json", "/lists.json")) %>
<li><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w", "/lists.json?last=4w")) %>
<li><%= ::Temple::Utils.escape_html((link_to '/lists.json?last=4w', '/lists.json?last=4w')) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and
<%= ::Temple::Utils.escape_html((Booru::CONFIG.settings[:max_images_per_page])) %>
)
</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpiboorust (Rust)', 'https://github.com/Ralvke/derpiboorust')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'dinky.js (JavaScript)', 'https://github.com/octet-stream/dinky')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json", "/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json", "/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json", "/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json", "/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w", "/lists.json?last=4w")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and
<%= ::Temple::Utils.escape_html((Booru::CONFIG.settings[:max_images_per_page])) %>
)
</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpiboorust (Rust)', 'https://github.com/Ralvke/derpiboorust')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'dinky.js (JavaScript)', 'https://github.com/octet-stream/dinky')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and
<%= ::Temple::Utils.escape_html((Booru::CONFIG.settings[:max_images_per_page])) %>
)
</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpiboorust (Rust)', 'https://github.com/Ralvke/derpiboorust')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'dinky.js (JavaScript)', 'https://github.com/octet-stream/dinky')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>min_score</code>
</td>
<td>Minimum score for images</td>
</tr>
<tr>
<td>
<code>max_score</code>
</td>
<td>Maximum score for images</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and
<%= ::Temple::Utils.escape_html((Booru::CONFIG.settings[:max_images_per_page])) %>
)
</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpiboorust (Rust)', 'https://github.com/Ralvke/derpiboorust')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'dinky.js (JavaScript)', 'https://github.com/octet-stream/dinky')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>min_score</code>
</td>
<td>Minimum score for images</td>
</tr>
<tr>
<td>
<code>max_score</code>
</td>
<td>Maximum score for images</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and
<%= ::Temple::Utils.escape_html((Booru::CONFIG.settings[:max_images_per_page])) %>
)
</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpiboorust (Rust)', 'https://github.com/Ralvke/derpiboorust')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>min_score</code>
</td>
<td>Minimum score for images</td>
</tr>
<tr>
<td>
<code>max_score</code>
</td>
<td>Maximum score for images</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and
<%= ::Temple::Utils.escape_html((Settings.max_images_per_page)) %>
<%= ::Temple::Utils.escape_html((Booru::CONFIG.settings[:max_images_per_page])) %>
)
</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpiboorust (Rust)', 'https://github.com/Ralvke/derpiboorust')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>min_score</code>
</td>
<td>Minimum score for images</td>
</tr>
<tr>
<td>
<code>max_score</code>
</td>
<td>Maximum score for images</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and
<%= ::Temple::Utils.escape_html((Settings.max_images_per_page)) %>
)
</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<p>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.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>min_score</code>
</td>
<td>Minimum score for images</td>
</tr>
<tr>
<td>
<code>max_score</code>
</td>
<td>Maximum score for images</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and
<%= ::Temple::Utils.escape_html((Settings.max_images_per_page)) %>
)
</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>min_score</code>
</td>
<td>Minimum score for images</td>
</tr>
<tr>
<td>
<code>max_score</code>
</td>
<td>Maximum score for images</td>
</tr>
<tr>
<td>
<code>perpage</code>
</td>
<td>
How many results to return on each page (must be between 1 and
<%= ::Temple::Utils.escape_html((Settings.max_images_per_page)) %>
)
</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search?q=my:faves?key=#{key}", "/search?q=my:faves?key=#{key}")) %>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:faves&key=#{key}", "/search.json?q=my:faves&key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/search?q=my:upvotes?key=#{key}", "/search?q=my:upvotes?key=#{key}")) %>
<li><%= ::Temple::Utils.escape_html((link_to "/search.json?q=my:upvotes&key=#{key}", "/search.json?q=my:upvotes&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=first_seen_at.gt:3+days+ago', '/search.json?q=first_seen_at.gt:3+days+ago')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
<li><%= ::Temple::Utils.escape_html((link_to "/search?q=my:faves?key=#{key}", "/search?q=my:faves?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
<li><%= ::Temple::Utils.escape_html((link_to "/search?q=my:upvotes?key=#{key}", "/search?q=my:upvotes?key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>This service supports maxwidth and maxheight parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://derpiboo.ru/*</li>
<li>https://derpiboo.ru/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<h1>API</h1>
<% content_for(:robots, true)
%><h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://derpiboo.ru/*</li>
<li>https://derpiboo.ru/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} does not have to refer to the gallery owner; in fact, the value of this parameter is ignored, only its presence matters.</p>
<p>Note that {user_name} is not required to refer to the gallery owner, however if it does not, the request is redirected (301) to the correct URL.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://derpiboo.ru/*</li>
<li>https://derpiboo.ru/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs features in each gallery, in the order defined by the owning user, disregarding content filters.</td>
<td>When set, include arrays of image IDs featured in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} does not have to refer to the gallery owner; in fact, the value of this parameter is ignored, only its presence matters.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://derpiboo.ru/*</li>
<li>https://derpiboo.ru/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
<td>The page offset. (The number of images per page is taken from user settings. For unauthenticated requests, the default value is 15.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset.</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>Image Galleries</h3>
<h4>
/galleries/{user_name}.json
</h4>
<p>Returns all galleries belonging to the specified user.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Showing 20 items per page.)</td>
</tr>
<tr>
<td>
<code>include_images</code>
</td>
<td>When set, include arrays of image IDs features in each gallery, in the order defined by the owning user, disregarding content filters.</td>
</tr>
</tbody>
</table>
<h4>
/galleries/{user_name}/{gallery_id}.json
</h4>
<p>
Returns images featured in the specified gallery along with information about the gallery itself. Compare this to using the previous endpoint coupled with
<code>include_images</code>
parameter set. In this case, the response contains an array of image objects, identical to those returned by image listing requests defined above, and not IDs.
Content filters are respected as well.
</p>
<p>Note that {user_name} does not have to refer to the gallery owner; in fact, the value of this parameter is ignored, only its presence matters.</p>
<table class="table">
<thead>
<tr>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (Refer to Image Index section for more information.)</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://derpiboo.ru/*</li>
<li>https://derpiboo.ru/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<table class="table">
<thead>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="pretty-table">
<tbody>
<table class="table">
<thead>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<table class="table">
<thead>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
<th>Parameter</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://derpiboo.ru/*</li>
<li>https://derpiboo.ru/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
<tr>
<td>
<code>random_image</code>
</td>
<td>When set, order the images randomly.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://derpiboo.ru/*</li>
<li>https://derpiboo.ru/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://derpiboo.ru/*</li>
<li>https://derpiboo.ru/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://derpiboo.ru/*</li>
<li>https://derpiboo.ru/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id_number, created_at, updated_at, and either deletion_reason or duplicate_of.
For such images, metadata is limited to id, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_id_number, derpibooru_score, derpibooru_comments</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://derpiboo.ru/*</li>
<li>https://derpiboo.ru/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>
<h1>API</h1>
<div class="walloftext">
<% key = current_user ? current_user.authentication_token : 'yourkey'
%><p>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 webapps that use the data provided within Derpibooru.</p>
<h2>Licensing</h2>
<p>Licensing of the API is simple - anyone can use it, users making abusively high numbers of requests may be asked to stop. Your application MUST properly cache, respect server-side cache expiry times. Your client MUST gracefully back off if requests fail (eg non-200 HTTP code), preferably exponentially or fatally.</p>
<p>Credit MUST always be given to the site in the form of a link. 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 URIs; Derpibooru does not support plaintext HTTP connections.</p>
<h2>Accessing the API</h2>
<p>
Most methods support API access by appending the extension .json 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. This key can be found by users on their account page. For instance, to access a user"s watched feed, the request
<code><%= ::Temple::Utils.escape_html(("/images/watched.json?key=#{key}")) %>
</code> would be made.
</p>
<p>Methods dealing with large feeds are paginated; the "page" parameter controls the page you're on. The number of images 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.</p>
<p>Search endpoints are controlled by the current user's filter (or the default, if no key is supplied); if you wish to using a custom filter, you can use the "filter_id" parameter.</p>
<h2>Libraries</h2>
<p>Some developers have written libraries for the Derpibooru API and made them available. Please contact us if you'd like yours listed here.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to 'DerPyBooru (Python)', 'https://github.com/joshua-stone/DerPyBooru')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to 'derpigo (Go)', 'https://github.com/Xe/derpigo')) %>
</li>
</ul>
<h2>Available Methods</h2>
<p>
Basic methods for fetching image lists and information are available. To access the JSON API for a given image page, simply add
<code>.json</code>
to the end of the path. Here are a few incredibly exciting examples.
</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images.json","/images.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/44819.json","/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/44819.json","/images/44819.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie', '/search.json?q=pinkie+pie')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to '/search.json?q=pinkie+pie&page=2' , '/search.json?q=pinkie+pie&page=2')) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json","/lists.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists.json?last=4w","/lists.json?last=4w")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json", "/lists/top_scoring.json")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/lists/top_scoring.json?page=2", "/lists/top_scoring.json?page=2")) %>
</li>
</ul>
<p>Note the list pages default to a 7 day sampling period; this can be altered with a URL parameter such as 6h, 24h, 7d, 4w.</p>
<p>Authenticated requests take a key argument - your personal key is shown in these requests as an example.</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to "/images/watched.json?key=#{key}", "/images/watched.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?key=#{key}", "/images/upvoted.json?key=#{key}")) %>
</li>
<li><%= ::Temple::Utils.escape_html((link_to "/images/upvoted.json?page=2&key=#{key}", "/images/upvoted.json?page=2&key=#{key}")) %>
</li>
</ul>
<h2>Available Parameters</h2>
<p>All page parameters are 1-indexed.</p>
<h3>
Image Index (
<code><%= ::Temple::Utils.escape_html((link_to '/images.json', '/images.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>constraint</code>
</td>
<td>
Search and sort by a specific field. (See also the note on page offsets below.)
<br />
Currently, the field can be:
<ul>
<li>id - to search by ID number</li>
<li>updated - to search by last update time</li>
<li>created - to search by image creation time</li>
</ul>Time fields are in ISO 8601 format (the same format which is returned).
</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>gt</code>
</td>
<td>When specified, constraint field must be greater than this value.</td>
</tr>
<tr>
<td>
<code>gte</code>
</td>
<td>When specified, constraint field must be greater than or equal to this value.</td>
</tr>
<tr>
<td>
<code>lt</code>
</td>
<td>When specified, constraint field must be less than this value.</td>
</tr>
<tr>
<td>
<code>lte</code>
</td>
<td>When specified, constraint field must be less than or equal to this value.</td>
</tr>
<tr>
<td>
<code>order</code>
</td>
<td>Sort order for constraint; either 'a' (ascending) or 'd' (descending). The default order is 'a'.</td>
</tr>
<tr>
<td>
<code>deleted</code>
</td>
<td>
When set, includes limited information about deleted and duplicate images in the results.
For such images, metadata is limited to id_number, created_at, updated_at, and either deletion_reason or duplicate_of.
</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Lists (
<code><%= ::Temple::Utils.escape_html((link_to '/lists.json', '/lists.json')) %>
</code>,
<code><%= ::Temple::Utils.escape_html((link_to '/lists/top_scoring.json', '/lists/top_scoring.json')) %>
</code>, etc.)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset. (See also note below.)</td>
</tr>
<tr>
<td>
<code>last</code>
</td>
<td>Sampling period, specified in weeks, days, or hours.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h3>
Image Search (
<code><%= ::Temple::Utils.escape_html((link_to '/search.json', '/search.json')) %>
</code>)
</h3>
<table class="pretty-table">
<tbody>
<tr>
<th class="center">Parameter</th>
<th class="center">Function</th>
</tr>
<tr>
<td>
<code>q</code>
</td>
<td>The search query. (Replace spaces with "+".)</td>
</tr>
<tr>
<td>
<code>page</code>
</td>
<td>The page offset.</td>
</tr>
<tr>
<td>
<code>comments</code>
</td>
<td>When set, include comment arrays; only enable this if you really need it, and consider using per-image requests for this information.</td>
</tr>
<tr>
<td>
<code>fav</code>
</td>
<td>When set, include favorited-by arrays. Only enable this if you really need it.</td>
</tr>
</tbody>
</table>
<h2>oEmbed</h2>
<p>For embedding content in other websites as well as for finding canonical image descriptors and IDs, we provide an oEmbed API.</p>
<p>
This API is compliant to the
<%= ::Temple::Utils.escape_html((link_to 'oEmbed specification', 'http://oembed.com/')) %>
and can be found at
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.json', 'https://derpibooru.org/oembed.json')) %>
or
<%= ::Temple::Utils.escape_html((link_to 'https://derpibooru.org/oembed.xml', 'https://derpibooru.org/oembed.xml')) %>
</p>
<p>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.</p>
<p>
<strong>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.</strong>
A cache age parameter is provided, which your client SHOULD respect for oEmbed requests themselves.
</p>
<p>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 image's page on Derpibooru.</p>
<p>In addition to the standard oEmbed photo attributes, the following attributes are also provided: derpibooru_id, derpibooru_id_number, derpibooru_score, derpibooru_comments</p>
<p>The following domain spaces are supported (for derpibooru.org and other domains, the format is the same). /media/ and /img/ URLs are only supported on derpicdn.net.</p>
<p>
<code>
<ul>
<li>https://derpibooru.org/*</li>
<li>https://derpibooru.org/images/*</li>
<li>https://derpiboo.ru/*</li>
<li>https://derpiboo.ru/images/*</li>
<li>https://trixiebooru.org/*</li>
<li>https://trixiebooru.org/images/*</li>
<li>https://derpicdn.net/img/*</li>
</ul>
</code></p>
<p>For example:</p>
<ul>
<li><%= ::Temple::Utils.escape_html((link_to '/oembed.json?url=https://derpibooru.org/17842', '/oembed.json?url=https://derpibooru.org/17842')) %>
</li>
</ul>
<p>This service supports maxheight and maxwidth parameters; these will return a fully formed thumbnail.</p>
<p>For tools that support it, the Derpibooru HTML header is embellished with appropriate oEmbed lookup link tags for automatic oEmbed discovery.</p>
</div>