This page has details for how to interact with tag records through the API.
01 Record field format
[hr]
[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]name[/code][/td]
[td]string[/td]
[td][/td]
[/tr]
[tr]
[td][code]category[/code][/td]
[td]integer[/td]
[td]includes [0,1,3,4,5][/td]
[/tr]
[tr]
[td][code]post_count[/code][/td]
[td]integer[/td]
[td]>=0[/td]
[/tr]
[tr]
[td][code]is_deprecated[/code][/td]
[td]boolean[/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]
Category
[table]
[thead]
[tr]
[th]Value[/th]
[th]Description[/th]
[/tr]
[/thead]
[tbody]
[tr]
[td]0[/td]
[td]General[/td]
[/tr]
[tr]
[td]1[/td]
[td]Artist[/td]
[/tr]
[tr]
[td]3[/td]
[td]Copyright[/td]
[/tr]
[tr]
[td]4[/td]
[td]Character[/td]
[/tr]
[tr]
[td]5[/td]
[td]Meta[/td]
[/tr]
[/tbody]
[/table]
[hr]
02 Associated attributes
[hr]
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]wiki_page[/code][/td]
[td]wiki page[/td]
[td]single[/td]
[td]optional[/td]
[td]Wiki page whose title matches the tag name.[/td]
[/tr]
[tr]
[td][code]artist[/code][/td]
[td]artist[/td]
[td]single[/td]
[td]optional[/td]
[td]Artist whose name matches the tag name.[/td]
[/tr]
[tr]
[td][code]antecedent_alias[/code][/td]
[td]tag alias[/td]
[td]single[/td]
[td]optional[/td]
[td]Alias where the tag is the antecedent.[/td]
[/tr]
[tr]
[td][code]consequent_aliases[/code][/td]
[td]tag alias[/td]
[td]multiple[/td]
[td]optional[/td]
[td]Aliases where the tag is the consequent.[/td]
[/tr]
[tr]
[td][code]antecedent_implications[/code][/td]
[td]tag implication[/td]
[td]multiple[/td]
[td]optional[/td]
[td]Implications where the tag is the antecedent.[/td]
[/tr]
[tr]
[td][code]consequent_implications[/code][/td]
[td]tag implication[/td]
[td]multiple[/td]
[td]optional[/td]
[td]Implications where the tag is the consequent.[/td]
[/tr]
[tr]
[td][code]dtext_links[/code][/td]
[td]dtext link[/td]
[td]multiple[/td]
[td]optional[/td]
[td]Dtext links to the page whose title matches the tag name.[/td]
[/tr]
[/tbody]
[/table]
03 Index
[hr]
Returns multiple tag records.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]GET[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/tags.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]
Search attributes
Search parameters take the following format (see Help:Common URL Parameters for more info):
[code]
search[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]category[/code]
- [code]post_count[/code]
- [code]created_at[/code]
- [code]updated_at[/code]
- String syntax
- [code]name[/code]
- Boolean syntax
- [code]is_deprecated[/code]
- Chaining syntax
- [code]wiki_page[/code]
- [code]artist[/code]
- [code]antecedent_alias[/code]
- [code]consequent_aliases[/code]
- [code]antecedent_implications[/code]
- [code]consequent_implications[/code]
- [code]consequent_implications[/code]
- [code]dtext_links[/code]
Special search parameters
The following are additional search fields.
- [code]fuzzy_name_matches[/code] - Shows tags with names that are within a certain percentage of similarity.
- [code]name_matches[/code] - Normalized wildcard search on the name field.
- [code]name_normalize[/code] - Normalized wildcard search on the name field that supports multiple tags split by a comma ",".
- [code]name_or_alias_matches[/code] - Normalized wildcard search on the name field that also checks for aliases where the search term is the antecedent.
- [code]hide_empty[/code] - Shows tags with a post count of 0 (true) or all tags (false) (Help:Boolean Syntax).
- [code]is_empty[/code] - Shows tags with a post count of 0 (true) or a post count greater than 0 (false) (Help:Boolean Syntax).
Search order
Using the search parameter [code]order[/code] with one of the following values changes the order of the results.
- [code]name[/code] - Name ascending.
- [code]date[/code] - ID descending.
- [code]count[/code] - Post count descending.
- [code]similarity[/code] - Orders by similarity to the search term, then by post count descending, then tag name ascending.
- Only when the [code]fuzzy_name_matches[/code] parameter is used.
- [code]custom[/code] - Help:Common URL Parameters
- In order to use this order, [code]search[id][/code] must also be set with a list of comma-separated IDs.
04 Show
[hr]
Returns a single tag record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]GET[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/tags/$id.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]read request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the tag ID.[/td]
[/tr]
[/tbody]
[/table]
05 Update
[hr]
Updates a single tag record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]PUT/PATCH[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/tags/$id.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the tag ID.[/td]
[/tr]
[/tbody]
[/table]
Update parameters
Tag parameters take the following format (see Help:API Write Requests for more info):
[code]
tag[FIELD]=VALUE
[/code]
- Optional:
- [code]is_deprecated[/code]
- can only be set to [code]false[/code] by admins
- can only be set to [code]true[/code] if the tag has a wiki page, and either its post count is zero or the user is an admin
- [code]category[/code] Restricted by user level
- Member+: < 50 posts
- Builder+: < 1000 posts
- Admin+: No limit
06 See also
[hr]
07 External links
[hr]
[table]
[tbody]
[tr]
[td]Controller[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/controllers/tags_controller.rb>[/td]
[td][/td]
[/tr]
[tr]
[td]Model[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/models/tag.rb>[/td]
[/tr]
[tr]
[td]Policy[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/policies/tag_policy.rb>[/td]
[/tr]
[/tbody]
[/table]