This page has details for how to interact with post records through the API.
[hr]
Record field format
[table]
[thead]
[tr]
[th]Name[/th]
[th]Type[/th]
[th]Details[/th]
[/tr]
[/thead]
[tbody]
[tr]
[td][code]id[/code][/td]
[td]integer[/td]
[td]>0[/td]
[/tr]
[tr]
[td][code]rating[/code][/td]
[td]string[/td]
[td]includes [g, s, q, e][/td]
[/tr]
[tr]
[td][code]parent_id[/code][/td]
[td]integer or null[/td]
[td]>0[/td]
[/tr]
[tr]
[td][code]source[/code][/td]
[td]string[/td]
[td][/td]
[/tr]
[tr]
[td][code]md5[/code][/td]
[td]string[/td]
[td]Only shown if visible to the user.[/td]
[/tr]
[tr]
[td][code]uploader_id[/code][/td]
[td]integer[/td]
[td]>0[/td]
[/tr]
[tr]
[td][code]approver_id[/code][/td]
[td]integer or null[/td]
[td]>0[/td]
[/tr]
[tr]
[td][code]file_ext[/code][/td]
[td]string[/td]
[td][/td]
[/tr]
[tr]
[td][code]file_size[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]image_width[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]image_height[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]score[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]up_score[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]down_score[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]fav_count[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]is_pending[/code][/td]
[td]boolean[/td]
[td][/td]
[/tr]
[tr]
[td][code]is_flagged[/code][/td]
[td]boolean[/td]
[td][/td]
[/tr]
[tr]
[td][code]is_deleted[/code][/td]
[td]boolean[/td]
[td][/td]
[/tr]
[tr]
[td][code]tag_string[/code][/td]
[td]string[/td]
[td][/td]
[/tr]
[tr]
[td][code]tag_count[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]tag_count_general[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]tag_count_artist[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]tag_count_copyright[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]tag_count_character[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]tag_count_meta[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]last_commented_at[/code][/td]
[td]timestamp or null[/td]
[td][/td]
[/tr]
[tr]
[td][code]last_comment_bumped_at[/code][/td]
[td]timestamp or null[/td]
[td][/td]
[/tr]
[tr]
[td][code]last_noted_at[/code][/td]
[td]timestamp or null[/td]
[td][/td]
[/tr]
[tr]
[td][code]has_children[/code][/td]
[td]boolean[/td]
[td][/td]
[/tr]
[tr]
[td][code]has_active_children[/code][/td]
[td]boolean[/td]
[td][/td]
[/tr]
[tr]
[td][code]pixiv_id[/code][/td]
[td]integer or null[/td]
[td]>0[/td]
[/tr]
[tr]
[td][code]bit_flags[/code][/td]
[td]bigint[/td]
[td][/td]
[/tr]
[tr]
[td][code]created_at[/code][/td]
[td]timestamp[/td]
[td][/td]
[/tr]
[tr]
[td][code]updated_at[/code][/td]
[td]timestamp[/td]
[td][/td]
[/tr]
[/tbody]
[/table]
[hr]
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.
[table]
[thead]
[tr]
[th]Name[/th]
[th]Type[/th]
[th]Details[/th]
[th]Notes[/th]
[/tr]
[/thead]
[tbody]
[tr]
[td][code]has_large[/code][/td]
[td]boolean[/td]
[td][/td]
[td]Derived from the media asset. The existence of the sample size.[/td]
[/tr]
[tr]
[td][code]has_visible_children[/code][/td]
[td]boolean[/td]
[td][/td]
[td]Derived from the children. Returns true if: - Any child is active - The user has it set to show deleted children - The post itself is deleted[/td]
[/tr]
[tr]
[td][code]file_url[/code][/td]
[td]string[/td]
[td]Only shown if visible to user.[/td]
[td]Derived from the media asset. The original size.[/td]
[/tr]
[tr]
[td][code]large_file_url[/code][/td]
[td]string[/td]
[td]Only shown if visible to user.[/td]
[td]Derived from the media asset, if the sample size exists.[/td]
[/tr]
[tr]
[td][code]preview_file_url[/code][/td]
[td]string[/td]
[td]Only shown if visible to user.[/td]
[td]Derived from the media asset. The 180x180 size.[/td]
[/tr]
[tr]
[td][code]tag_string_general[/code][/td]
[td]string[/td]
[td][/td]
[td]Derived from the tag string.[/td]
[/tr]
[tr]
[td][code]tag_string_artist[/code][/td]
[td]string[/td]
[td][/td]
[td]Derived from the tag string.[/td]
[/tr]
[tr]
[td][code]tag_string_copyright[/code][/td]
[td]string[/td]
[td][/td]
[td]Derived from the tag string.[/td]
[/tr]
[tr]
[td][code]tag_string_character[/code][/td]
[td]string[/td]
[td][/td]
[td]Derived from the tag string.[/td]
[/tr][tr]
[td][code]tag_string_meta[/code][/td]
[td]string[/td]
[td][/td]
[td]Derived from the tag string.[/td]
[/tr]
[/tbody]
[/table]
[hr]
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):
[table]
[thead]
[tr]
[th]Name[/th]
[th]Type[/th]
[th]Number[/th]
[th]Availability[/th]
[th]Details[/th]
[/tr]
[/thead]
[tbody]
[tr]
[td][code]media_asset[/code][/td]
[td]media asset[/td]
[td]single[/td]
[td]required[/td]
[td]Included by default.[/td]
[/tr]
[tr]
[td][code]media_metadata[/code][/td]
[td]media metadata[/td]
[td]single[/td]
[td]required[/td]
[td][/td]
[/tr]
[tr]
[td][code]uploader[/code][/td]
[td]user[/td]
[td]single[/td]
[td]required[/td]
[td][/td]
[/tr]
[tr]
[td][code]approver[/code][/td]
[td]user[/td]
[td]single[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]parent[/code][/td]
[td]post[/td]
[td]single[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]children[/code][/td]
[td]post[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]artist_commentary[/code][/td]
[td]artist_commentary[/td]
[td]single[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]notes[/code][/td]
[td]note[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]comments[/code][/td]
[td]comment[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]flags[/code][/td]
[td]post flag[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]appeals[/code][/td]
[td]post appeals[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]events[/code][/td]
[td]events[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]approvals[/code][/td]
[td]post approval[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]disapprovals[/code][/td]
[td]post disapproval[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]replacements[/code][/td]
[td]post replacement[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]ai_tags[/code][/td]
[td]ai tag[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]dtext_links[/code][/td]
[td]dtext link[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]embedding_wiki_pages[/code][/td]
[td]wiki page[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[/tbody]
[/table]
[hr]
Index
Returns multiple post records.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]GET[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/posts.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]read request[/td]
[/tr]
[tr]
[td]Description[/td]
[td]The default order is ID descending[/td]
[/tr]
[/tbody]
[/table]
Index parameters
- [code]tags[/code] - The post query to search for using tags and metatags (Help:Cheatsheet).
- [code]random[/code] - Selects a random sampling under the post query.
- [code]md5[/code] - 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:
[code]
search[post][FIELD]=VALUE
[/code]
The following are the base fields along with their associated type. Check the syntax pages for all of the available variations.
- Number syntax
- [code]id[/code]
- [code]created_at[/code]
- [code]updated_at[/code]
- [code]pixiv_id[/code]
- [code]fav_count[/code]
- [code]score[/code]
- [code]up_score[/code]
- [code]down_score[/code]
- [code]file_size[/code]
- [code]image_width[/code]
- [code]image_height[/code]
- [code]tag_count[/code]
- [code]last_comment_bumped_at[/code]
- [code]last_commented_at[/code]
- [code]last_noted_at[/code]
- Text syntax
- [code]rating[/code]
- [code]source[/code]
- [code]md5[/code]
- [code]file_ext[/code]
- Boolean syntax
- [code]has_children[/code]
- [code]has_active_children[/code]
- [code]is_pending[/code]
- [code]is_flagged[/code]
- [code]is_deleted[/code]
- [code]is_banned[/code]
- User syntax
- [code]uploader[/code]
- [code]approver[/code]
- Post syntax
- [code]parent[/code] (unavailable due to current limitations)
- [code]children[/code] (unavailable due to current limitations)
- Chaining syntax
- [code]artist_commentary[/code]
- [code]flags[/code]
- [code]appeals[/code]
- [code]notes[/code]
- [code]comments[/code]
- [code]approvals[/code]
- [code]replacements[/code]
- [code]media_metadata[/code]
Special search parameters
The following are additional search fields.
- [code]tags[/code] - Behaves the same as the regular post search.
[hr]
Show
Returns a single post record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]GET[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/posts/$id.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]read request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the post ID[/td]
[/tr]
[/tbody]
[/table]
[hr]
Create
Creates a single post record.
[table]
[tr]
[td]HTTP method[/td]
[td]POST[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td]/posts.json[/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[/table]
Create parameters
Post parameters take the following format (see Help:API Write Requests for more info):
[code]
post[FIELD]=VALUE
[/code]
- Mandatory:
- [code]upload_media_asset_id[/code]
- Optional:
- [code]tag_string[/code]
- [code]rating[/code]
- [code]parent_id[/code]
- [code]source[/code]
- [code]artist_commentary_title[/code]
- [code]artist_commentary_desc[/code]
- [code]translated_commentary_title[/code]
- [code]translated_commentary_desc[/code]
- [code]is_pending[/code] - only matters for users with unrestricted uploads.
[hr]
Update
Updates a single post record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]PUT/PATCH[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/posts/$id.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td]$id is the post ID[/td]
[/tr]
[/tbody]
[/table]
Update parameters
- Optional:
- [code]tag_string[/code]
- [code]old_tag_string[/code]
- [code]parent_id[/code]
- [code]old_parent_id[/code]
- [code]source[/code]
- [code]old_source[/code]
- [code]rating[/code]
- [code]old_rating[/code]
- [code]has_embedded_notes[/code]
[hr]
Destroy
Deletes a single post record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]DELETE[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/posts/$id.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td]$id is the post ID Only available to Approvers and above.[/td]
[/tr]
[/tbody]
[/table]
Revert
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]PUT/PATCH[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/posts/$id/revert.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td]$id is the post ID[/td]
[/tr]
[/tbody]
[/table]
Revert parameters
- Required:
- version_id - The post version ID to revert to.
[hr]
See also
[hr]
External links
[table]
[tbody]
[tr]
[td]Controller[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/controllers/posts_controller.rb>[/td]
[td][/td]
[/tr]
[tr]
[td]Model[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/models/post.rb>[/td]
[/tr]
[tr]
[td]Policy[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/policies/post_policy.rb>[/td]
[/tr]
[/tbody]
[/table]