animedex.backends.danbooru

High-level Danbooru Python API.

Eight commands wrapping the most-used anonymous read endpoints on danbooru.donmai.us: search / post / artist / artist-search / tag / pool / pool-search / count.

The Danbooru tag-DSL surface is rich (rating filters, score comparators, order: sorting, exclusion via -tag); the high- level search() accepts the raw tag string verbatim and forwards it to the upstream. The project’s posture per the Human Agency Principle: when the user did not explicitly ask for adult content, LLM agents should prepend rating:g to the tag query themselves; the CLI / library never injects a content filter on the user’s behalf.

• animedex.backends.danbooru.models
  • DanbooruPost
    • DanbooruPost
  • DanbooruArtist
    • DanbooruArtist
  • DanbooruTag
    • DanbooruTag
  • DanbooruPool
    • DanbooruPool
  • DanbooruProfile
    • DanbooruProfile
  • DanbooruSavedSearch
    • DanbooruSavedSearch
  • DanbooruRecord
    • DanbooruRecord
  • DanbooruRelatedTag
    • DanbooruRelatedTag
  • DanbooruIQDBQuery
    • DanbooruIQDBQuery
  • DanbooruCount
    • DanbooruCount
  • selftest
    • selftest()

search

animedex.backends.danbooru.search(tags: str | None = None, *, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruPost]

Tag-DSL search via /posts.json.

Parameters:

• tags (str or None) – Space-separated tag query (the upstream’s DSL). rating:g, order:score, score:>100, -tag (exclusion) and user:<name> are all honoured by the upstream. When None, the upstream returns the latest posts unfiltered.

• limit (int) – Max rows per page.

• page (int) – 1-indexed page number.

Returns:

List of typed posts.

Return type:

list[DanbooruPost]

post

animedex.backends.danbooru.post(id: int, *, config: Config | None = None, **kw) → DanbooruPost

Fetch one post by its numeric Danbooru ID via /posts/{id}.json.

Parameters:

id (int) – Danbooru post ID.

Returns:

Typed post.

Return type:

DanbooruPost

artist

animedex.backends.danbooru.artist(id: int, *, config: Config | None = None, **kw) → DanbooruArtist

Fetch one artist by ID via /artists/{id}.json.

Parameters:

id (int) – Danbooru artist ID.

Returns:

Typed artist.

Return type:

DanbooruArtist

artist_search

animedex.backends.danbooru.artist_search(name: str, *, limit: int = 20, config: Config | None = None, **kw) → List[DanbooruArtist]

Search artists by name (substring match) via /artists.json?search[any_name_or_url_matches]=<name>.

Parameters:

• name (str) – Substring to match against name / alias / URL.

• limit (int) – Max rows per page.

Returns:

List of typed artists.

Return type:

list[DanbooruArtist]

tag

animedex.backends.danbooru.tag(name: str, *, limit: int = 20, config: Config | None = None, **kw) → List[DanbooruTag]

Look up a tag by exact or prefix-match name via /tags.json?search[name_matches]=<name>.

Returns a list because the upstream’s name_matches accepts wildcards (e.g. touhou*); pass an exact name to get a single-element list.

Parameters:

• name (str) – Tag name (or wildcard pattern).

• limit (int) – Max rows per page.

Returns:

List of typed tags.

Return type:

list[DanbooruTag]

pool

animedex.backends.danbooru.pool(id: int, *, config: Config | None = None, **kw) → DanbooruPool

Fetch one pool by ID via /pools/{id}.json.

Parameters:

id (int) – Danbooru pool ID.

Returns:

Typed pool.

Return type:

DanbooruPool

pool_search

animedex.backends.danbooru.pool_search(name: str | None = None, *, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruPool]

Search pools by name substring via /pools.json?search[name_matches]=<name>.

Parameters:

• name (str or None) – Pool name substring; None lists all pools.

• limit (int) – Max rows per page.

• page (int) – 1-indexed page number.

Returns:

List of typed pools.

Return type:

list[DanbooruPool]

count

animedex.backends.danbooru.count(tags: str | None = None, *, config: Config | None = None, **kw) → DanbooruCount

Count posts matching a tag query via /counts/posts.json?tags=<tags>.

Parameters:

tags (str or None) – Space-separated tag query (same DSL as search()); None counts the entire catalogue.

Returns:

Typed count envelope; access .total() for the int.

Return type:

DanbooruCount

artist_versions

animedex.backends.danbooru.artist_versions(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Edit history for artist records via /artist_versions.json.

artist_commentaries

animedex.backends.danbooru.artist_commentaries(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Artist-supplied commentary text for posts via /artist_commentaries.json.

artist_commentary

animedex.backends.danbooru.artist_commentary(id: int, *, config: Config | None = None, **kw) → DanbooruRecord

One artist commentary by id via /artist_commentaries/{id}.json.

artist_commentary_versions

animedex.backends.danbooru.artist_commentary_versions(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Edit history for commentaries via /artist_commentary_versions.json.

tag_aliases

animedex.backends.danbooru.tag_aliases(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Tag aliases (synonyms) via /tag_aliases.json.

tag_implications

animedex.backends.danbooru.tag_implications(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Tag implications (parent → child) via /tag_implications.json.

tag_versions

animedex.backends.danbooru.tag_versions(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Edit history for tag records via /tag_versions.json.

wiki_pages

animedex.backends.danbooru.wiki_pages(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Tag wiki page collection via /wiki_pages.json.

wiki_page

animedex.backends.danbooru.wiki_page(id: int, *, config: Config | None = None, **kw) → DanbooruRecord

One wiki page by id via /wiki_pages/{id}.json.

wiki_page_versions

animedex.backends.danbooru.wiki_page_versions(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Wiki-page edit history via /wiki_page_versions.json.

pool_versions

animedex.backends.danbooru.pool_versions(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Pool edit history via /pool_versions.json.

notes

animedex.backends.danbooru.notes(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Translation overlay notes on posts via /notes.json.

note

animedex.backends.danbooru.note(id: int, *, config: Config | None = None, **kw) → DanbooruRecord

One note by id via /notes/{id}.json.

note_versions

animedex.backends.danbooru.note_versions(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Note edit history via /note_versions.json.

comments

animedex.backends.danbooru.comments(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Post comments via /comments.json.

comment

animedex.backends.danbooru.comment(id: int, *, config: Config | None = None, **kw) → DanbooruRecord

One comment by id via /comments/{id}.json.

comment_votes

animedex.backends.danbooru.comment_votes(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Comment vote feed via /comment_votes.json.

forum_topics

animedex.backends.danbooru.forum_topics(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Forum topic listing via /forum_topics.json.

forum_topic_visits

animedex.backends.danbooru.forum_topic_visits(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Forum topic visit feed via /forum_topic_visits.json.

forum_posts

animedex.backends.danbooru.forum_posts(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Forum post listing via /forum_posts.json.

forum_post_votes

animedex.backends.danbooru.forum_post_votes(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Forum-post vote feed via /forum_post_votes.json.

users

animedex.backends.danbooru.users(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

User directory via /users.json.

user

animedex.backends.danbooru.user(id: int, *, config: Config | None = None, **kw) → DanbooruRecord

One user by id via /users/{id}.json.

user_events

animedex.backends.danbooru.user_events(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

User-event feed via /user_events.json.

user_feedbacks

animedex.backends.danbooru.user_feedbacks(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Moderator-recorded user feedback via /user_feedbacks.json.

favorites

animedex.backends.danbooru.favorites(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Favourite-record feed via /favorites.json (anonymous-readable on the public subset).

favorite_groups

animedex.backends.danbooru.favorite_groups(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Favourite-group listing via /favorite_groups.json.

uploads

animedex.backends.danbooru.uploads(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Upload-record feed via /uploads.json.

upload_media_assets

animedex.backends.danbooru.upload_media_assets(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Media assets attached to uploads via /upload_media_assets.json.

post_versions

animedex.backends.danbooru.post_versions(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Post edit history via /post_versions.json.

post_replacements

animedex.backends.danbooru.post_replacements(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Post-image replacement records via /post_replacements.json.

post_disapprovals

animedex.backends.danbooru.post_disapprovals(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Mod-disapproval records via /post_disapprovals.json.

post_appeals

animedex.backends.danbooru.post_appeals(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Removal-appeal records via /post_appeals.json.

post_flags

animedex.backends.danbooru.post_flags(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

User-submitted post flag records via /post_flags.json.

post_votes

animedex.backends.danbooru.post_votes(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Post-vote feed via /post_votes.json.

post_approvals

animedex.backends.danbooru.post_approvals(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Mod-approval records via /post_approvals.json.

post_events

animedex.backends.danbooru.post_events(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Post-event audit log via /post_events.json.

autocomplete

animedex.backends.danbooru.autocomplete(query: str, *, type: str = 'tag_query', limit: int = 10, config: Config | None = None, **kw) → List[DanbooruRecord]

Tag / artist autocomplete via /autocomplete.json?search[query]=<q>&search[type]=<type>.

Parameters:

• query (str) – Prefix to autocomplete.

• type (str) – Autocomplete dictionary; common values are tag_query (default), artist, pool, user, wiki_page.

• limit (int) – Max suggestions.

related_tag

animedex.backends.danbooru.related_tag(query: str, *, limit: int = 20, config: Config | None = None, **kw) → DanbooruRelatedTag

Tag-graph navigation via /related_tag.json?query=<q>.

Returns a list of tags that frequently co-occur with the input on Danbooru posts. Useful for query refinement.

iqdb_query

animedex.backends.danbooru.iqdb_query(*, url: str | None = None, post_id: int | None = None, config: Config | None = None, **kw) → List[DanbooruIQDBQuery]

Reverse image lookup via /iqdb_queries.json?url=<u> or ?post_id=<id>.

Use url= for an external image URL or post_id= to find Danbooru posts visually similar to an existing one.

mod_actions

animedex.backends.danbooru.mod_actions(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Moderator-action audit log via /mod_actions.json.

bans

animedex.backends.danbooru.bans(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Account-ban records via /bans.json.

bulk_update_requests

animedex.backends.danbooru.bulk_update_requests(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Bulk-update tag-graph requests via /bulk_update_requests.json.

dtext_links

animedex.backends.danbooru.dtext_links(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

DText hyperlink graph via /dtext_links.json.

ai_tags

animedex.backends.danbooru.ai_tags(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

AI-classifier tag suggestions via /ai_tags.json.

media_assets

animedex.backends.danbooru.media_assets(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Underlying media-asset records via /media_assets.json.

media_metadata

animedex.backends.danbooru.media_metadata(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Media-asset EXIF / dimensions metadata via /media_metadata.json.

rate_limits

animedex.backends.danbooru.rate_limits(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Per-user / per-IP rate-limit-ledger via /rate_limits.json.

recommended_posts

animedex.backends.danbooru.recommended_posts(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Per-user post recommendations via /recommended_posts.json.

reactions

animedex.backends.danbooru.reactions(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Reaction-emoji records via /reactions.json.

jobs

animedex.backends.danbooru.jobs(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Background-job ledger via /jobs.json.

metrics

animedex.backends.danbooru.metrics(*, limit: int = 20, page: int = 1, config: Config | None = None, **kw) → List[DanbooruRecord]

Operational metric snapshots via /metrics.json.

profile

animedex.backends.danbooru.profile(*, creds: Tuple[str, str] | None = None, config: Config | None = None, **kw) → DanbooruProfile

The authenticated user’s own profile via /profile.json.

Returns the typed DanbooruProfile; the upstream payload carries the user’s level, upload counters, blacklisted tags, and similar account-scoped state.

saved_searches

animedex.backends.danbooru.saved_searches(*, limit: int = 20, page: int = 1, creds: Tuple[str, str] | None = None, config: Config | None = None, **kw) → List[DanbooruSavedSearch]

The authenticated user’s saved searches via /saved_searches.json.

Each row carries the saved search’s tag query plus an optional label list the user organises bookmarks by.

selftest

animedex.backends.danbooru.selftest() → bool

Smoke-test the public Danbooru Python API (signatures only, no network).

Returns:

True on success.

Return type:

bool