api:posts

Table of Contents

This page has details for how to interact with post records through the API.

Record field format

NameTypeDetails
idinteger>0
ratingstringincludes [g, s, q, e]
parent_idinteger or null>0
sourcestring
md5stringOnly shown if visible to the user.
uploader_idinteger>0
approver_idinteger or null>0
file_extstring
file_sizeinteger
image_widthinteger
image_heightinteger
scoreinteger
up_scoreinteger
down_scoreinteger
fav_countinteger
is_pendingboolean
is_flaggedboolean
is_deletedboolean
tag_stringstring
tag_countinteger
tag_count_generalinteger
tag_count_artistinteger
tag_count_copyrightinteger
tag_count_characterinteger
tag_count_metainteger
last_commented_attimestamp or null
last_comment_bumped_attimestamp or null
last_noted_attimestamp or null
has_childrenboolean
has_active_childrenboolean
pixiv_idinteger or null>0
bit_flagsbigint
created_attimestamp
updated_attimestamp

Derived field format

These are values which are not part of the actual record, but instead are derived from calculations and record lookups on the fly.

NameTypeDetailsNotes
has_largebooleanDerived from the media asset. The existence of the sample size.
has_visible_childrenbooleanDerived from the children. Returns true if:
- Any child is active
- The user has it set to show deleted children
- The post itself is deleted
file_urlstringOnly shown if visible to user.Derived from the media asset. The original size.
large_file_urlstringOnly shown if visible to user.Derived from the media asset, if the sample size exists.
preview_file_urlstringOnly shown if visible to user.Derived from the media asset. The 180x180 size.
tag_string_generalstringDerived from the tag string.
tag_string_artiststringDerived from the tag string.
tag_string_copyrightstringDerived from the tag string.
tag_string_characterstringDerived from the tag string.
tag_string_metastringDerived from the tag string.

Associated attributes

The following is the list of relations that can be included in the API results (see Help:Common URL parameters for more info):

NameTypeNumberAvailabilityDetails
media_assetmedia assetsinglerequiredIncluded by default.
media_metadatamedia metadatasinglerequired
uploaderusersinglerequired
approverusersingleoptional
parentpostsingleoptional
childrenpostmultipleoptional
artist_commentaryartist_commentarysingleoptional
notesnotemultipleoptional
commentscommentmultipleoptional
flagspost flagmultipleoptional
appealspost appealsmultipleoptional
eventseventsmultipleoptional
approvalspost approvalmultipleoptional
disapprovalspost disapprovalmultipleoptional
replacementspost replacementmultipleoptional
ai_tagsai tagmultipleoptional
dtext_linksdtext linkmultipleoptional
embedding_wiki_pageswiki pagemultipleoptional

Index

Returns multiple post records.

HTTP MethodGET
Base URL/posts.json
Typeread request
DescriptionThe default order is ID descending
Index parameters
  • tags - The post query to search for using tags and metatags (Help:Cheatsheet).
  • random - Selects a random sampling under the post query.
  • md5 - Search for an MD5 match. Takes priority over all other parameters.
Search attributes

Search parameters are not available directly, but can be used via chaining (see Help:Chaining Syntax for more info). The following is an example of what this format can look like:

search[post][FIELD]=VALUE

The following are the base fields along with their associated type. Check the syntax pages for all of the available variations.

  • Number syntax
    • id
    • created_at
    • updated_at
    • pixiv_id
    • fav_count
    • score
    • up_score
    • down_score
    • file_size
    • image_width
    • image_height
    • tag_count
    • last_comment_bumped_at
    • last_commented_at
    • last_noted_at
  • Text syntax
    • rating
    • source
    • md5
    • file_ext
  • Boolean syntax
    • has_children
    • has_active_children
    • is_pending
    • is_flagged
    • is_deleted
    • is_banned
  • User syntax
    • uploader
    • approver
  • Post syntax
    • parent (unavailable due to current limitations)
    • children (unavailable due to current limitations)
  • Chaining syntax
    • artist_commentary
    • flags
    • appeals
    • notes
    • comments
    • approvals
    • replacements
    • media_metadata
Special search parameters

The following are additional search fields.

  • tags - Behaves the same as the regular post search.

Show

Returns a single post record.

HTTP MethodGET
Base URL/posts/$id.json
Typeread request
Description$id is the post ID

Create

Creates a single post record.

HTTP methodPOST
Base URL/posts.json
Typewrite request
Create parameters

Post parameters take the following format (see Help:API Write Requests for more info):

post[FIELD]=VALUE
  • Mandatory:
    • upload_media_asset_id
  • Optional:
    • tag_string
    • rating
    • parent_id
    • source
    • artist_commentary_title
    • artist_commentary_desc
    • translated_commentary_title
    • translated_commentary_desc
    • is_pending - only matters for users with unrestricted uploads.

Update

Updates a single post record.

HTTP MethodPUT/PATCH
Base URL/posts/$id.json
Typewrite request
Description$id is the post ID
Update parameters
  • Optional:
    • tag_string
    • old_tag_string
    • parent_id
    • old_parent_id
    • source
    • old_source
    • rating
    • old_rating
    • has_embedded_notes

Destroy

Deletes a single post record.

HTTP MethodDELETE
Base URL/posts/$id.json
Typewrite request
Description$id is the post ID
Only available to Approvers and above.

Revert

HTTP MethodPUT/PATCH
Base URL/posts/$id/revert.json
Typewrite request
Description$id is the post ID
Revert parameters
  • Required:
    • version_id - The post version ID to revert to.

See also

Controllerhttps://github.com/danbooru/danbooru/blob/master/app/controllers/posts_controller.rb
Modelhttps://github.com/danbooru/danbooru/blob/master/app/models/post.rb
Policyhttps://github.com/danbooru/danbooru/blob/master/app/policies/post_policy.rb