animedex danbooru
Danbooru is a community-driven anime art catalogue hosted at
https://danbooru.donmai.us. It is the deepest tag-DSL surface
animedex wraps: every post / artist / tag / pool / wiki page /
forum thread / commentary / vote / version / moderation event.
animedex covers 57 anonymous endpoints plus 2 authenticated
read endpoints as 59 high-level Python functions.
References
Site |
|
API help |
|
Tag DSL guide |
|
Python module |
|
Rich models |
Backend: Danbooru (danbooru.donmai.us).
Rate limit: 10 req/sec anonymous; transport bucket matches.
Auth: optional. Most endpoints work without credentials; the user-private surface (
/profil e,/saved_searches) needs an HTTP Basicusername:api_keypair from the user’s account Settings → API Keys page.
NSFW posture
Danbooru’s tag DSL exposes content ratings via rating:g (general),
rating:s (sensitive), rating:q (questionable), and rating:e
(explicit). The project’s posture per the Human Agency Principle:
animedex never injects rating filters on the user’s behalf. A query like
touhou marisago es through unchanged; the upstream decides what to return.LLM agents using this CLI as a tool should prepend
rating:gto the tag query when the user has not explicitly asked for adult / ecchi / NSFW content. When th e user explicitly asks for it, pass the query through unmodifi ed.Every result row carries a
.ratingfield so a downstream pipeline can re-filter.
This advice ships in the Click command’s docstring + the
--agent-guide extraction; see the
the project README’s “Human Agency Principle” section page for the broader policy.
Eight endpoints, in detail
Tag-DSL search — search()
animedex danbooru search 'touh ou marisa rating:g order:score' --limit 3 \
--jq '.[] | {id, score, rati ng, file_url}'
One post — post()
animedex danbooru post 1 --jq '{id, rating, score, source}'
Artist lookup — artist()
animedex danbooru artist-searc h "Hayao Miyazaki" --limit 3 --jq '.[].name'
Tag wildcard — tag()
animedex danbooru tag "touhou* " --limit 5 --jq '.[] | {name, post_count}'
Tag autocomplete — autocomplete()
animedex danbooru autocomplete touh --type tag_query --jq '.[].label'
Post count — count()
animedex danbooru count 'touho u rating:g' --jq '.counts.posts'
Reverse image lookup — iqdb_query()
animedex danbooru iqdb-query - -post-id 1 --jq '.[] | {post_id, score}'
Authenticated endpoints
Two reads need the caller’s own HTTP Basic credentials. Get an API key from https://danbooru.donmai.us/profile → “API Key” section (create a new key with read-only scope). Provide via:
# Per-call (CLI):
animedex danbooru profile --cr eds "username:api_key"
# Per-shell (env var):
export ANIMEDEX_DANBOORU_CREDS ="username:api_key"
animedex danbooru profile
Authenticated walkthrough
Own profile — profile()
animedex danbooru profile --jq '{name, level, post_upload_count, blacklisted_tags}'
Saved searches — saved_searches()
animedex danbooru saved-search es --limit 5 --jq '.[].query'
Endpoint summary
Discovery
Command |
Python entry point |
Returns |
|---|---|---|
|
|
|
|
||
|
|
Long-tail feeds (catch-all DanbooruRecord)
Command |
Python entry point |
Returns |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Authenticated reads
Command |
Python entry point |
Returns |
|---|---|---|
|
||
|
|
Pagination
Danbooru paginates with ?limit=M&page=N (1-indexed). The
high-level helpers expose limit / page kwargs:
animedex danbooru search "touh ou rating:g" --limit 5 --page 1
animedex danbooru search "touh ou rating:g" --limit 5 --page 2
Gotchas
The catch-all ``DanbooruRecord`` type covers the long tail of versions / votes / events / for um / commentary / moderation feeds with a single rich shape. Its ` id` field is typed as
Anybecause op erational endpoints (/jobs,/metrics) use UUID strings while the typical ones use ints —extra='allow'round-trips b oth.Empty result is an empty list, not 404: a tag search with no hits returns
[]with HTTP 2 00.``iqdb-query`` requires ``–url`` or ``–post-id``: passing neither raises
ApiError(reaso n="bad-args").403 on``/dmails`` is not an animedex bug: that endpoint requires Gold-tier upstream membership. animedex surfaces the upstream’s reason directly.
The Python library page covers the same surface from inside Python.