This page has details for how to interact with artist 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]name[/code][/td]
[td]string[/td]
[td]tag format[/td]
[/tr]
[tr]
[td][code]group_name[/code][/td]
[td]string[/td]
[td][/td]
[/tr]
[tr]
[td][code]other_names[/code][/td]
[td]array[/td]
[td]strings[/td]
[/tr]
[tr]
[td][code]is_banned[/code][/td]
[td]boolean[/td]
[td][/td]
[/tr]
[tr]
[td][code]is_deleted[/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]
[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]members[/code][/td]
[td]artist[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]urls[/code][/td]
[td]artist url[/td]
[td]multiple[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]wiki_page[/code][/td]
[td]wiki page[/td]
[td]single[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]tag_alias[/code][/td]
[td]tag alias[/td]
[td]single[/td]
[td]optional[/td]
[td][/td]
[/tr]
[tr]
[td][code]tag[/code][/td]
[td]tag[/td]
[td]single[/td]
[td]optional[/td]
[td][/td]
[/tr]
[/tbody]
[/table]
[hr]
Index
Returns multiple artist records.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]GET[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/artists.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]created_at[/code]
- [code]updated_at[/code]
- String syntax
- [code]name[/code]
- [code]group_name[/code]
- Boolean syntax
- [code]is_deleted[/code]
- [code]is_banned[/code]
- Array syntax
- [code]other_names[/code]
- Chaining syntax
- [code]urls[/code]
- [code]wiki_page[/code]
- [code]tag_alias[/code]
- [code]tag[/code]
Special search parameters
The following are additional search fields.
- [code]any_other_name_like[/code] - Search for artists that have an other name matching this value. Supports wildcards.
- [code]any_name_matches[/code] - Search for artists that have a matching name, group name, or other name. Supports wildcards and regexes.
- [code]url_matches[/code] - Search for artists with a matching URL.
- Does a regex match when the query starts and ends with a forward slash "/".
- Regexes must follow the Ruby's format.
- Does a wildcard match when there are asterisks "*" present.
- Uses the artist URL finder when the value is prefaced by [code]http://[/code] or [code]https://[/code]
- This does a recursive search on URLs stripping the pathname one level at a time to search for matches.
- It will keep searching until it finds an exact match or 10 similar entries.
- Otherwise it does a wildcard search with wildcard placed at the start and end.
- [code]any_name_or_url_matches[/code] - Searches for the artist by name or URL.
- Does a URL search if the value is prefaced by [code]http://[/code] or [code]https://[/code]
- Does a name search otherwise.
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 descending.
- [code]updated_at[/code] - Updated at descending.
- [code]post_count[/code] - Post count descending.
- [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.
[hr]
Show
Returns a single artist record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]GET[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/artists/$id.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]read request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the artist ID.[/td]
[/tr]
[/tbody]
[/table]
[hr]
Create
Creates a single artist record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]POST[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/artists.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[/tbody]
[/table]
Create parameters
Artist parameters take the following format (see Help:API Write Requests for more info):
[code]
artist[FIELD]=VALUE
[/code]
- Required:
- [code]name[/code]- The artist tag name.
- Must be tag format (API:Tags).
- Optional
- [code]group_name[/code] - The name of the group this artist belongs to.
- [code]other_names[/code] - List of alternative names for this artist.
- Space delimited. Replace spaces within names with underscores.
- [code]url_string[/code] - List of URLs associated with this artist
- Whitespace or newline delimited.
- [code]is_deleted[/code] - Set the artist entry as deleted or not.
[hr]
Update
Updates a single artist record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]PUT/PATCH[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/artists/$id.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the artist ID.[/td]
[/tr]
[/tbody]
[/table]
Update parameters
Accepts the same parameters as the Create action. All parameters are optional.
[hr]
Delete
Deletes a single artist record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]DELETE[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/artists/$id.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the artist ID.[/td]
[/tr]
[/tbody]
[/table]
Note: The action can be accomplished using the Update action by setting [code]is_deleted[/code] to true.
[hr]
Revert
Reverts a single artist record to a prior version.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]PUT[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/artists/$id/revert.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the artist ID.[/td]
[/tr]
[/tbody]
[/table]
Revert parameters
- Required:
- version_id - The artist version ID to revert to.
Note: The version ID may be passed along as a URL parameter instead of in the body.
[hr]
Ban
Bans a single artist record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]PUT[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/artists/$id/ban.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the artist ID.
Restricted to Admins only (Help:Users)[/td]
[/tr]
[/tbody]
[/table]
[hr]
Unban
Unbans a single artist record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]PUT[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/artists/$id/unban.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the artist ID.
Restricted to Admins only (Help:Users)[/td]
[/tr]
[/tbody]
[/table]
[hr]
See also
[hr]
External links
[table]
[tbody]
[tr]
[td]Controller[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/controllers/artists_controller.rb>[/td]
[td][/td]
[/tr]
[tr]
[td]Model[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/models/artist.rb>[/td]
[/tr]
[tr]
[td]Policy[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/policies/artist_policy.rb>[/td]
[/tr]
[/tbody]
[/table]