King-of-the-all-Cookies/ayako
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b983126e6ed81cf1948768007115522975b68c1b
ayako/API.mhtml
King-of-the-all-Cookies b983126e6e First commit
2026-05-01 15:13:02 +03:00

3412 lines
122 KiB
Mason
Raw Blame History

From: <Saved by Blink>
Snapshot-Content-Location: https://api.vndb.org/kana
Subject: VNDB.org API v2 (Kana)
Date: Fri, 1 May 2026 14:37:04 +0300
MIME-Version: 1.0
Content-Type: multipart/related;
type="text/html";
boundary="----MultipartBoundary--iFOSnX79r9F8KpuRTSwwVgShnV5hBx9uvFtLF8zrAZ----"
------MultipartBoundary--iFOSnX79r9F8KpuRTSwwVgShnV5hBx9uvFtLF8zrAZ----
Content-Type: text/html
Content-ID: <frame-60E740040F54079D3EEEEBD2C076D032@mhtml.blink>
Content-Transfer-Encoding: quoted-printable
Content-Location: https://api.vndb.org/kana
<!DOCTYPE html><html xmlns=3D"http://www.w3.org/1999/xhtml" lang=3D"" xml:l=
ang=3D"" class=3D" idc0_343 lquetgb"><head><meta http-equiv=3D"Content-Type=
" content=3D"text/html; charset=3DUTF-8"><link rel=3D"stylesheet" type=3D"t=
ext/css" href=3D"cid:css-4278df0f-2856-4d8e-9d4c-63ab937f01cb@mhtml.blink" =
/><link rel=3D"stylesheet" type=3D"text/css" href=3D"cid:css-d65ec0c8-f004-=
4010-8603-861f49b335f5@mhtml.blink" />
=20
<meta name=3D"generator" content=3D"pandoc">
<meta name=3D"viewport" content=3D"width=3Ddevice-width, initial-scale=3D=
1.0, user-scalable=3Dyes">
<title>VNDB.org API v2 (Kana)</title>
=20
=20
</head>
<body>
<header id=3D"title-block-header">
<h1 class=3D"title">VNDB.org API v2 (Kana)</h1>
</header>
<nav id=3D"TOC" role=3D"doc-toc">
<ul>
<li><a href=3D"https://api.vndb.org/kana#introduction" id=3D"toc-introducti=
on">Introduction</a></li>
<li><a href=3D"https://api.vndb.org/kana#usage-terms" id=3D"toc-usage-terms=
">Usage Terms</a></li>
<li><a href=3D"https://api.vndb.org/kana#common-data-types" id=3D"toc-commo=
n-data-types">Common Data
Types</a></li>
<li><a href=3D"https://api.vndb.org/kana#user-authentication" id=3D"toc-use=
r-authentication">User
Authentication</a></li>
<li><a href=3D"https://api.vndb.org/kana#simple-requests" id=3D"toc-simple-=
requests">Simple
Requests</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#get-schema" id=3D"toc-get-schema">=
GET /schema</a></li>
<li><a href=3D"https://api.vndb.org/kana#get-stats" id=3D"toc-get-stats">GE=
T /stats</a></li>
<li><a href=3D"https://api.vndb.org/kana#get-user" id=3D"toc-get-user">GET =
/user</a></li>
<li><a href=3D"https://api.vndb.org/kana#get-authinfo" id=3D"toc-get-authin=
fo">GET /authinfo</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#database-querying" id=3D"toc-datab=
ase-querying">Database
Querying</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#api-structure" id=3D"toc-api-struc=
ture">API Structure</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#query-format" id=3D"toc-query-form=
at">Query format</a></li>
<li><a href=3D"https://api.vndb.org/kana#response-format" id=3D"toc-respons=
e-format">Response
format</a></li>
<li><a href=3D"https://api.vndb.org/kana#filters" id=3D"toc-filters">Filter=
s</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#post-vn" id=3D"toc-post-vn">POST /=
vn</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#vn-filters" id=3D"toc-vn-filters">=
Filters</a></li>
<li><a href=3D"https://api.vndb.org/kana#vn-fields" id=3D"toc-vn-fields">Fi=
elds</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#post-release" id=3D"toc-post-relea=
se">POST /release</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#release-filters" id=3D"toc-release=
-filters">Filters</a></li>
<li><a href=3D"https://api.vndb.org/kana#release-fields" id=3D"toc-release-=
fields">Fields</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#post-producer" id=3D"toc-post-prod=
ucer">POST /producer</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#producer-filters" id=3D"toc-produc=
er-filters">Filters</a></li>
<li><a href=3D"https://api.vndb.org/kana#producer-fields" id=3D"toc-produce=
r-fields">Fields</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#post-character" id=3D"toc-post-cha=
racter">POST
/character</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#character-filters" id=3D"toc-chara=
cter-filters">Filters</a></li>
<li><a href=3D"https://api.vndb.org/kana#character-fields" id=3D"toc-charac=
ter-fields">Fields</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#post-staff" id=3D"toc-post-staff">=
POST /staff</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#staff-filters" id=3D"toc-staff-fil=
ters">Filters</a></li>
<li><a href=3D"https://api.vndb.org/kana#staff-fields" id=3D"toc-staff-fiel=
ds">Fields</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#post-tag" id=3D"toc-post-tag">POST=
/tag</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#filters-1" id=3D"toc-filters-1">Fi=
lters</a></li>
<li><a href=3D"https://api.vndb.org/kana#tag-fields" id=3D"toc-tag-fields">=
Fields</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#post-trait" id=3D"toc-post-trait">=
POST /trait</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#filters-2" id=3D"toc-filters-2">Fi=
lters</a></li>
<li><a href=3D"https://api.vndb.org/kana#trait-fields" id=3D"toc-trait-fiel=
ds">Fields</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#post-quote" id=3D"toc-post-quote">=
POST /quote</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#filters-3" id=3D"toc-filters-3">Fi=
lters</a></li>
<li><a href=3D"https://api.vndb.org/kana#quote-fields" id=3D"toc-quote-fiel=
ds">Fields</a></li>
</ul></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#list-management" id=3D"toc-list-ma=
nagement">List
Management</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#post-ulist" id=3D"toc-post-ulist">=
POST /ulist</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#ulist-fields" id=3D"toc-ulist-fiel=
ds">Fields</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#get-ulist_labels" id=3D"toc-get-ul=
ist_labels">GET
/ulist_labels</a></li>
<li><a href=3D"https://api.vndb.org/kana#patch-ulistid" id=3D"toc-patch-uli=
stid">PATCH
/ulist/&lt;id&gt;</a></li>
<li><a href=3D"https://api.vndb.org/kana#patch-rlistid" id=3D"toc-patch-rli=
stid">PATCH
/rlist/&lt;id&gt;</a></li>
<li><a href=3D"https://api.vndb.org/kana#delete-ulistid" id=3D"toc-delete-u=
listid">DELETE
/ulist/&lt;id&gt;</a></li>
<li><a href=3D"https://api.vndb.org/kana#delete-rlistid" id=3D"toc-delete-r=
listid">DELETE
/rlist/&lt;id&gt;</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#http-response-codes" id=3D"toc-htt=
p-response-codes">HTTP
Response Codes</a></li>
<li><a href=3D"https://api.vndb.org/kana#tips-troubleshooting" id=3D"toc-ti=
ps-troubleshooting">Tips
&amp; Troubleshooting</a>
<ul>
<li><a href=3D"https://api.vndb.org/kana#too-much-data-selected" id=3D"toc-=
too-much-data-selected">=E2=80=9CToo much data selected=E2=80=9D</a></li>
<li><a href=3D"https://api.vndb.org/kana#list-of-identifiers" id=3D"toc-lis=
t-of-identifiers">List of
identifiers</a></li>
<li><a href=3D"https://api.vndb.org/kana#pagination" id=3D"toc-pagination">=
Pagination</a></li>
<li><a href=3D"https://api.vndb.org/kana#random" id=3D"toc-random">Random e=
ntry</a></li>
</ul></li>
<li><a href=3D"https://api.vndb.org/kana#change-log" id=3D"toc-change-log">=
Change Log</a></li>
</ul>
</nav>
<h1 id=3D"introduction">Introduction</h1>
<p>This document describes the HTTPS API to query information from the
<a href=3D"https://vndb.org/">VNDB</a> database and manage user lists.</p>
<p>This version of the API replaces the <a href=3D"https://api.vndb.org/nya=
n">old TCP-based API</a>.</p>
<p><strong>API endpoint</strong>: <code>https://api.vndb.org/kana</code></p=
>
<p>A sandbox endpoint is available for testing and development at <a href=
=3D"https://beta.vndb.org/api/kana">https://beta.vndb.org/api/kana</a>,
for more information see <a href=3D"https://beta.vndb.org/about-sandbox">th=
e sandbox</a>.</p>
<h1 id=3D"usage-terms">Usage Terms</h1>
<p>This service is free for non-commercial use. The API is provided on a
best-effort basis, no guarantees are made about the stability or
applicability of this service.</p>
<p>The data obtained through this API is subject to our <a href=3D"https://=
vndb.org/d17#4">Data License</a>.</p>
<p>API access is rate-limited in order to keep server resources in
check. The server will allow up to 200 requests per 5 minutes and up to
1 second of execution time per minute. Requests taking longer than 3
seconds will be aborted. These limits should be more than enough for
most applications, but if this is still too limiting for you, don=E2=80=99t
hesitate to get in touch.</p>
<p>This API intentionally does not expose <em>all</em> functionality
provided by VNDB. Some site features, such as forums, database editing
or account creation will not be exposed through the API, other features
may be missing simply because nobody has asked for it yet. If you need
anything not yet provided by the API or if you have any other questions,
feel free to post on <a href=3D"https://vndb.org/t/db">the forums</a>, <a h=
ref=3D"https://code.blicky.net/yorhel/vndb/issues">the issue tracker</a>
or mail <a href=3D"mailto:contact@vndb.org">contact@vndb.org</a>.</p>
<h1 id=3D"common-data-types">Common Data Types</h1>
<dl>
<dt>vndbid</dt>
<dd>
A =E2=80=98vndbid=E2=80=99 is an identifier for an entry in the database, t=
ypically
formatted as a number with a one or two character prefix, e.g.&nbsp;=E2=80=
=9Cv17=E2=80=9D
refers to <a href=3D"https://vndb.org/v17">this visual novel</a> and
=E2=80=9Csf190=E2=80=9D refers to <a href=3D"https://vndb.org/img/sf190">th=
is
screenshot</a>.
</dd>
<dd>
The API will return vndbids as a JSON string, but the filters also
accept bare integers if the prefix is unambiguous from the context.
</dd>
<dt>release date</dt>
<dd>
Release dates are represented as JSON strings as either
<code>"YYYY-MM-DD"</code>, <code>"YYYY-MM"</code> or <code>"YYYY"</code>
formats, depending on whether the day and month are known. Unspecified
future dates are returned as <code>"TBA"</code>. The values
<code>"unknown"</code> and <code>"today"</code> are also supported in
filters.
</dd>
<dd>
Partial dates are ordered <em>after</em> complete dates for the same
year/month, i.e.&nbsp;<code>"2022"</code> is ordered after
<code>"2022-12"</code>, which in turn is ordered after
<code>"2022-12-31"</code>. This can be unintuitive when writing filters:
<code>["released", "&lt;", "2022-01"]</code> also matches all complete
dates in Jan 2022. Likewise, <code>["released", "=3D", "2022"]</code> only
matches items for which the release date is exactly <code>"2022"</code>,
not any other date in that year.
</dd>
<dt>enumeration types</dt>
<dd>
Several fields in the database are represented as an integer or string
with a limited number of possible values. These values are either
documented for the particular field or listed separately in the <a href=3D"=
https://api.vndb.org/kana#get-schema">schema JSON</a>.
</dd>
</dl>
<h1 id=3D"user-authentication">User Authentication</h1>
<p>The majority of the API endpoints below are usable without any form
of authentication, but some user-related actions - in particular, list
management - require the calls to be authenticated with the respective
VNDB user account.</p>
<p>The API understands cookies originating from the main
<code>vndb.org</code> domain, so user scripts running from the site only
have to ensure that <a href=3D"https://developer.mozilla.org/en-US/docs/Web=
/API/XMLHttpRequest/withCredentials">XMLHttpRequest.withCredentials</a>
or <a href=3D"https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Us=
ing_Fetch#sending_a_request_with_credentials_included">the
Fetch API =E2=80=9Ccredentials=E2=80=9D parameter</a> is set.</p>
<p>In all other cases, token authentication should to be used. Users can
obtain a token by opening their =E2=80=9CMy Profile=E2=80=9D form and going=
to the
=E2=80=9CApplications=E2=80=9D tab. The URL <code>https://vndb.org/u/tokens=
</code> can
also be used to redirect users to this form. Tokens look like
<code>xxxx-xxxxx-xxxxx-xxxx-xxxxx-xxxxx-xxxx</code>, with each
<code>x</code> representing a lowercase z-base-32 character. The dashes
in between are optional.</p>
<p>Tokens may be included in API requests using the
<code>Authorization</code> header with the <code>Token</code> type, for
example:</p>
<pre><code>Authorization: Token hsoo-ybws4-j8yb9-qxkw-5obay-px8to-bfyk</cod=
e></pre>
<p>A HTTP 401 error is returned if the token is invalid. The <a href=3D"htt=
ps://api.vndb.org/kana#get-authinfo">GET /authinfo</a> endpoint can be used=
validate and
extract information from tokens.</p>
<h1 id=3D"simple-requests">Simple Requests</h1>
<h2 id=3D"get-schema">GET /schema</h2>
<p>Returns a <a href=3D"https://api.vndb.org/kana/schema">JSON object</a> w=
ith metadata
about several API objects, including enumeration values, which fields
are available for querying and a list of supported external links. The
JSON structure is hopefully self-explanatory.</p>
<p>This information does not change very often and can safely be used
for code generation or dynamic API introspection.</p>
<p>The <code>url_format</code> attribute of external links is purely
informational and should not be used to construct URLs. The API has
custom URL formatting rules for various sites that may not match this
<code>url_format</code>.</p>
<h2 id=3D"get-stats">GET /stats</h2>
<p>Returns a few overall database statistics.</p>
<p><code>curl https://api.vndb.org/kana/stats</code></p>
<div class=3D"sourceCode" id=3D"cb2"><pre class=3D"sourceCode json"><code c=
lass=3D"sourceCode json"><span id=3D"cb2-1"><a href=3D"https://api.vndb.org=
/kana#cb2-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"fu">{<=
/span></span>
<span id=3D"cb2-2"><a href=3D"https://api.vndb.org/kana#cb2-2" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"chars"</span><span clas=
s=3D"fu">:</span> <span class=3D"dv">112347</span><span class=3D"fu">,</spa=
n></span>
<span id=3D"cb2-3"><a href=3D"https://api.vndb.org/kana#cb2-3" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"producers"</span><span =
class=3D"fu">:</span> <span class=3D"dv">14789</span><span class=3D"fu">,</=
span></span>
<span id=3D"cb2-4"><a href=3D"https://api.vndb.org/kana#cb2-4" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"releases"</span><span c=
lass=3D"fu">:</span> <span class=3D"dv">91490</span><span class=3D"fu">,</s=
pan></span>
<span id=3D"cb2-5"><a href=3D"https://api.vndb.org/kana#cb2-5" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"staff"</span><span clas=
s=3D"fu">:</span> <span class=3D"dv">27929</span><span class=3D"fu">,</span=
></span>
<span id=3D"cb2-6"><a href=3D"https://api.vndb.org/kana#cb2-6" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"tags"</span><span class=
=3D"fu">:</span> <span class=3D"dv">2783</span><span class=3D"fu">,</span><=
/span>
<span id=3D"cb2-7"><a href=3D"https://api.vndb.org/kana#cb2-7" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"traits"</span><span cla=
ss=3D"fu">:</span> <span class=3D"dv">3115</span><span class=3D"fu">,</span=
></span>
<span id=3D"cb2-8"><a href=3D"https://api.vndb.org/kana#cb2-8" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"vn"</span><span class=
=3D"fu">:</span> <span class=3D"dv">36880</span></span>
<span id=3D"cb2-9"><a href=3D"https://api.vndb.org/kana#cb2-9" aria-hidden=
=3D"true" tabindex=3D"-1"></a><span class=3D"fu">}</span></span></code></pr=
e></div>
<h2 id=3D"get-user">GET /user</h2>
<p>Lookup users by id or username. Accepts two query parameters:</p>
<dl>
<dt>q</dt>
<dd>
User ID or username to look up, can be given multiple times to look up
multiple users.
</dd>
<dt>fields</dt>
<dd>
List of fields to select. The =E2=80=98id=E2=80=99 and =E2=80=98username=E2=
=80=99 fields are always
selected and should not be specified here.
</dd>
</dl>
<p>The response object contains one key for each given <code>q</code>
parameter, its value is either <code>null</code> if no such user was
found or otherwise an object with the following fields:</p>
<dl>
<dt>id</dt>
<dd>
String in <code>"u123"</code> format.
</dd>
<dt>username</dt>
<dd>
String.
</dd>
<dt>lengthvotes</dt>
<dd>
Integer, number of play time votes this user has submitted.
</dd>
<dt>lengthvotes_sum</dt>
<dd>
Integer, sum of the user=E2=80=99s play time votes, in minutes.
</dd>
</dl>
<p>Strings that look like user IDs are not valid usernames, so the
lookup is unambiguous. Usernames matching is case-insensitive.</p>
<p><code>curl 'https://api.vndb.org/kana/user?q=3DNoUserWithThisNameExists&=
amp;q=3DAYO&amp;q=3Du3'</code></p>
<div class=3D"sourceCode" id=3D"cb3"><pre class=3D"sourceCode json"><code c=
lass=3D"sourceCode json"><span id=3D"cb3-1"><a href=3D"https://api.vndb.org=
/kana#cb3-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"fu">{<=
/span></span>
<span id=3D"cb3-2"><a href=3D"https://api.vndb.org/kana#cb3-2" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"AYO"</span><span class=
=3D"fu">:</span> <span class=3D"fu">{</span></span>
<span id=3D"cb3-3"><a href=3D"https://api.vndb.org/kana#cb3-3" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"id"</span><span class=
=3D"fu">:</span> <span class=3D"st">"u3"</span><span class=3D"fu">,</span><=
/span>
<span id=3D"cb3-4"><a href=3D"https://api.vndb.org/kana#cb3-4" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"username"</span><span=
class=3D"fu">:</span> <span class=3D"st">"ayo"</span></span>
<span id=3D"cb3-5"><a href=3D"https://api.vndb.org/kana#cb3-5" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"fu">},</span></span>
<span id=3D"cb3-6"><a href=3D"https://api.vndb.org/kana#cb3-6" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"NoUserWithThisNameExist=
s"</span><span class=3D"fu">:</span> <span class=3D"kw">null</span><span cl=
ass=3D"fu">,</span></span>
<span id=3D"cb3-7"><a href=3D"https://api.vndb.org/kana#cb3-7" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"u3"</span><span class=
=3D"fu">:</span> <span class=3D"fu">{</span></span>
<span id=3D"cb3-8"><a href=3D"https://api.vndb.org/kana#cb3-8" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"id"</span><span class=
=3D"fu">:</span> <span class=3D"st">"u3"</span><span class=3D"fu">,</span><=
/span>
<span id=3D"cb3-9"><a href=3D"https://api.vndb.org/kana#cb3-9" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"username"</span><span=
class=3D"fu">:</span> <span class=3D"st">"ayo"</span></span>
<span id=3D"cb3-10"><a href=3D"https://api.vndb.org/kana#cb3-10" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"fu">}</span></span>
<span id=3D"cb3-11"><a href=3D"https://api.vndb.org/kana#cb3-11" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"fu">}</span></span></code></p=
re></div>
<p><code>curl 'https://api.vndb.org/kana/user?q=3Dyorhel&amp;fields=3Dlengt=
hvotes,lengthvotes_sum'</code></p>
<div class=3D"sourceCode" id=3D"cb4"><pre class=3D"sourceCode json"><code c=
lass=3D"sourceCode json"><span id=3D"cb4-1"><a href=3D"https://api.vndb.org=
/kana#cb4-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"fu">{<=
/span></span>
<span id=3D"cb4-2"><a href=3D"https://api.vndb.org/kana#cb4-2" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"yorhel"</span><span cla=
ss=3D"fu">:</span> <span class=3D"fu">{</span></span>
<span id=3D"cb4-3"><a href=3D"https://api.vndb.org/kana#cb4-3" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"id"</span><span class=
=3D"fu">:</span> <span class=3D"st">"u2"</span><span class=3D"fu">,</span><=
/span>
<span id=3D"cb4-4"><a href=3D"https://api.vndb.org/kana#cb4-4" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"lengthvotes"</span><s=
pan class=3D"fu">:</span> <span class=3D"dv">9</span><span class=3D"fu">,</=
span></span>
<span id=3D"cb4-5"><a href=3D"https://api.vndb.org/kana#cb4-5" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"lengthvotes_sum"</spa=
n><span class=3D"fu">:</span> <span class=3D"dv">9685</span><span class=3D"=
fu">,</span></span>
<span id=3D"cb4-6"><a href=3D"https://api.vndb.org/kana#cb4-6" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"username"</span><span=
class=3D"fu">:</span> <span class=3D"st">"Yorhel"</span></span>
<span id=3D"cb4-7"><a href=3D"https://api.vndb.org/kana#cb4-7" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"fu">}</span></span>
<span id=3D"cb4-8"><a href=3D"https://api.vndb.org/kana#cb4-8" aria-hidden=
=3D"true" tabindex=3D"-1"></a><span class=3D"fu">}</span></span></code></pr=
e></div>
<h2 id=3D"get-authinfo">GET /authinfo</h2>
<p>Validates and returns information about the given <a href=3D"https://api=
.vndb.org/kana#user-authentication">API token</a>. The JSON object has the
following members:</p>
<dl>
<dt>id</dt>
<dd>
String, user ID.
</dd>
<dt>username</dt>
<dd>
String, username.
</dd>
<dt>permissions</dt>
<dd>
Array of strings, permissions granted to this token.
</dd>
</dl>
<p>The following permissions are currently implemented:</p>
<dl>
<dt>listread</dt>
<dd>
Allows read access to private labels and entries in the user=E2=80=99s visu=
al
novel list.
</dd>
<dt>listwrite</dt>
<dd>
Allows write access to the user=E2=80=99s visual novel list.
</dd>
</dl>
<div class=3D"sourceCode" id=3D"cb5"><pre class=3D"sourceCode sh"><code cla=
ss=3D"sourceCode bash"><span id=3D"cb5-1"><a href=3D"https://api.vndb.org/k=
ana#cb5-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">curl=
</span> https://api.vndb.org/kana/authinfo<span class=3D"dt">\</span></span=
>
<span id=3D"cb5-2"><a href=3D"https://api.vndb.org/kana#cb5-2" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--header</span> <span =
class=3D"st">'Authorization: token cdhy-bqy1q-6zobu-8w9k-xobxh-wzz4o-84fn'<=
/span></span></code></pre></div>
<div class=3D"sourceCode" id=3D"cb6"><pre class=3D"sourceCode json"><code c=
lass=3D"sourceCode json"><span id=3D"cb6-1"><a href=3D"https://api.vndb.org=
/kana#cb6-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"fu">{<=
/span></span>
<span id=3D"cb6-2"><a href=3D"https://api.vndb.org/kana#cb6-2" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"id"</span><span class=
=3D"fu">:</span> <span class=3D"st">"u3"</span><span class=3D"fu">,</span><=
/span>
<span id=3D"cb6-3"><a href=3D"https://api.vndb.org/kana#cb6-3" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"username"</span><span c=
lass=3D"fu">:</span> <span class=3D"st">"ayo"</span><span class=3D"fu">,</s=
pan></span>
<span id=3D"cb6-4"><a href=3D"https://api.vndb.org/kana#cb6-4" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"permissions"</span><spa=
n class=3D"fu">:</span> <span class=3D"ot">[</span></span>
<span id=3D"cb6-5"><a href=3D"https://api.vndb.org/kana#cb6-5" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"st">"listread"</span></spa=
n>
<span id=3D"cb6-6"><a href=3D"https://api.vndb.org/kana#cb6-6" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"ot">]</span></span>
<span id=3D"cb6-7"><a href=3D"https://api.vndb.org/kana#cb6-7" aria-hidden=
=3D"true" tabindex=3D"-1"></a><span class=3D"fu">}</span></span></code></pr=
e></div>
<h1 id=3D"database-querying">Database Querying</h1>
<h2 id=3D"api-structure">API Structure</h2>
<p>Searching for and fetching database entries is done through a custom
query format<a href=3D"https://api.vndb.org/kana#fn1" class=3D"footnote-ref=
" id=3D"fnref1" role=3D"doc-noteref"><sup>1</sup></a>. Queries are sent as
<code>POST</code> requests, but I expect to also support the
<code>QUERY</code> HTTP method once that gains more software
support.</p>
<h3 id=3D"query-format">Query format</h3>
<p>A query is a JSON object that looks like this:</p>
<div class=3D"sourceCode" id=3D"cb7"><pre class=3D"sourceCode json"><code c=
lass=3D"sourceCode json"><span id=3D"cb7-1"><a href=3D"https://api.vndb.org=
/kana#cb7-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"fu">{<=
/span></span>
<span id=3D"cb7-2"><a href=3D"https://api.vndb.org/kana#cb7-2" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"filters"</span><span cl=
ass=3D"fu">:</span> <span class=3D"ot">[]</span><span class=3D"fu">,</span>=
</span>
<span id=3D"cb7-3"><a href=3D"https://api.vndb.org/kana#cb7-3" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"fields"</span><span cla=
ss=3D"fu">:</span> <span class=3D"st">""</span><span class=3D"fu">,</span><=
/span>
<span id=3D"cb7-4"><a href=3D"https://api.vndb.org/kana#cb7-4" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"sort"</span><span class=
=3D"fu">:</span> <span class=3D"st">"id"</span><span class=3D"fu">,</span><=
/span>
<span id=3D"cb7-5"><a href=3D"https://api.vndb.org/kana#cb7-5" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"reverse"</span><span cl=
ass=3D"fu">:</span> <span class=3D"kw">false</span><span class=3D"fu">,</sp=
an></span>
<span id=3D"cb7-6"><a href=3D"https://api.vndb.org/kana#cb7-6" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"results"</span><span cl=
ass=3D"fu">:</span> <span class=3D"dv">10</span><span class=3D"fu">,</span>=
</span>
<span id=3D"cb7-7"><a href=3D"https://api.vndb.org/kana#cb7-7" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"page"</span><span class=
=3D"fu">:</span> <span class=3D"dv">1</span><span class=3D"fu">,</span></sp=
an>
<span id=3D"cb7-8"><a href=3D"https://api.vndb.org/kana#cb7-8" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"user"</span><span class=
=3D"fu">:</span> <span class=3D"kw">null</span><span class=3D"fu">,</span><=
/span>
<span id=3D"cb7-9"><a href=3D"https://api.vndb.org/kana#cb7-9" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"count"</span><span clas=
s=3D"fu">:</span> <span class=3D"kw">false</span><span class=3D"fu">,</span=
></span>
<span id=3D"cb7-10"><a href=3D"https://api.vndb.org/kana#cb7-10" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"compact_filters"</span=
><span class=3D"fu">:</span> <span class=3D"kw">false</span><span class=3D"=
fu">,</span></span>
<span id=3D"cb7-11"><a href=3D"https://api.vndb.org/kana#cb7-11" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"normalized_filters"</s=
pan><span class=3D"fu">:</span> <span class=3D"kw">false</span></span>
<span id=3D"cb7-12"><a href=3D"https://api.vndb.org/kana#cb7-12" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"fu">}</span></span></code></p=
re></div>
<p>All members are optional, defaults are shown above.</p>
<dl>
<dt>filters</dt>
<dd>
Filters are used to determine which database items to fetch, see the
section on <a href=3D"https://api.vndb.org/kana#filters">Filters</a> below.
</dd>
<dt>fields</dt>
<dd>
String. Comma-separated list of fields to fetch for each database item.
Dot notation can be used to select nested JSON objects,
e.g.&nbsp;<code>"image.url"</code> will select the <code>url</code> field
inside the <code>image</code> object. Multiple nested fields can be
selected with brackets, e.g.&nbsp;<code>"image{id,url,dims}"</code> is
equivalent to <code>"image.id, image.url, image.dims"</code>.
</dd>
<dd>
Every field of interest must be explicitely mentioned, there is no
support for wildcard matching. The same applies to nested objects, it is
an error to list <code>image</code> without sub-fields in the example
above.
</dd>
<dd>
The top-level <code>id</code> field is always selected by default and
does not have to be mentioned in this list.
</dd>
<dt>sort</dt>
<dd>
Field to sort on. Supported values depend on the type of data being
queried and are documented separately.
</dd>
<dt>reverse</dt>
<dd>
Set to true to sort in descending order.
</dd>
<dt>results</dt>
<dd>
Number of results per page, max 100. Can also be set to <code>0</code>
if you=E2=80=99re not interested in the results at all, but just want to ve=
rify
your query or get the <code>count</code>, <code>compact_filters</code>
or <code>normalized_filters</code>.
</dd>
<dt>page</dt>
<dd>
Page number to request, starting from 1. See also the <a href=3D"https://ap=
i.vndb.org/kana#pagination">note on pagination</a> below.
</dd>
<dt>user</dt>
<dd>
User ID. This field is mainly used for <code>POST /ulist</code>, but it
also sets the default user ID to use for the visual novel =E2=80=9Clabel=E2=
=80=9D
filter. Defaults to the currently authenticated user.
</dd>
<dt>count</dt>
<dd>
Whether the response should include the <code>count</code> field (see
below). This option should be avoided when the count is not needed since
it has a considerable performance impact.
</dd>
<dt>compact_filters</dt>
<dd>
Whether the response should include the <code>compact_filters</code>
field (see below).
</dd>
<dt>normalized_filters</dt>
<dd>
Whether the response should include the <code>normalized_filters</code>
field (see below).
</dd>
</dl>
<h3 id=3D"response-format">Response format</h3>
<div class=3D"sourceCode" id=3D"cb8"><pre class=3D"sourceCode json"><code c=
lass=3D"sourceCode json"><span id=3D"cb8-1"><a href=3D"https://api.vndb.org=
/kana#cb8-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"fu">{<=
/span></span>
<span id=3D"cb8-2"><a href=3D"https://api.vndb.org/kana#cb8-2" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"results"</span><span cl=
ass=3D"fu">:</span> <span class=3D"ot">[]</span><span class=3D"fu">,</span>=
</span>
<span id=3D"cb8-3"><a href=3D"https://api.vndb.org/kana#cb8-3" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"more"</span><span class=
=3D"fu">:</span> <span class=3D"kw">false</span><span class=3D"fu">,</span>=
</span>
<span id=3D"cb8-4"><a href=3D"https://api.vndb.org/kana#cb8-4" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"count"</span><span clas=
s=3D"fu">:</span> <span class=3D"dv">1</span><span class=3D"fu">,</span></s=
pan>
<span id=3D"cb8-5"><a href=3D"https://api.vndb.org/kana#cb8-5" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"compact_filters"</span>=
<span class=3D"fu">:</span> <span class=3D"st">""</span><span class=3D"fu">=
,</span></span>
<span id=3D"cb8-6"><a href=3D"https://api.vndb.org/kana#cb8-6" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"dt">"normalized_filters"</sp=
an><span class=3D"fu">:</span> <span class=3D"ot">[]</span><span class=3D"f=
u">,</span></span>
<span id=3D"cb8-7"><a href=3D"https://api.vndb.org/kana#cb8-7" aria-hidden=
=3D"true" tabindex=3D"-1"></a><span class=3D"fu">}</span></span></code></pr=
e></div>
<dl>
<dt>results</dt>
<dd>
Array of objects representing the query results.
</dd>
<dt>more</dt>
<dd>
When <code>true</code>, repeating the query with an incremented
<code>page</code> number will yield more results. This is a cheaper form
of pagination than using the <code>count</code> field.
</dd>
<dt>count</dt>
<dd>
Only present if the query contained <code>"count":true</code>. Indicates
the total number of entries that matched the given filters.
</dd>
<dt>compact_filters</dt>
<dd>
Only present if the query contained <code>"compact_filters":true</code>.
This is a compact string representation of the filters given in the
query.
</dd>
<dt>normalized_filters</dt>
<dd>
Only present if the query contained
<code>"normalized_filters":true</code>. This is a normalized JSON
representation of the filters given in the query.
</dd>
</dl>
<h3 id=3D"filters">Filters</h3>
<p>Simple predicates are represented as a three-element JSON array
containing a filter name, operator and value,
e.g.&nbsp;<code>[ "id", "=3D", "v17" ]</code>. All filters accept the
(in)equality operators <code>=3D</code> and <code>!=3D</code>. Filters that
support ordering also accept <code>&gt;=3D</code>, <code>&gt;</code>,
<code>&lt;=3D</code> and <code>&lt;</code>. The full list of accepted
filter names and values is documented below for each type of database
item.</p>
<p>Simple predicates can be combined into larger queries with and/or
predicates. These are represented as JSON arrays where the first element
is either <code>"and"</code> or <code>"or"</code>, followed by two or
more other predicates.</p>
<p>Full example of a more complex visual novel filter (which, as of
writing, doesn=E2=80=99t actually match anything in the database):</p>
<div class=3D"sourceCode" id=3D"cb9"><pre class=3D"sourceCode json"><code c=
lass=3D"sourceCode json"><span id=3D"cb9-1"><a href=3D"https://api.vndb.org=
/kana#cb9-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ot">[<=
/span> <span class=3D"st">"and"</span></span>
<span id=3D"cb9-2"><a href=3D"https://api.vndb.org/kana#cb9-2" aria-hidden=
=3D"true" tabindex=3D"-1"></a><span class=3D"ot">,</span> <span class=3D"ot=
">[</span> <span class=3D"st">"or"</span></span>
<span id=3D"cb9-3"><a href=3D"https://api.vndb.org/kana#cb9-3" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"ot">,</span> <span class=3D"=
ot">[</span> <span class=3D"st">"lang"</span><span class=3D"ot">,</span> <s=
pan class=3D"st">"=3D"</span><span class=3D"ot">,</span> <span class=3D"st"=
>"en"</span> <span class=3D"ot">]</span></span>
<span id=3D"cb9-4"><a href=3D"https://api.vndb.org/kana#cb9-4" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"ot">,</span> <span class=3D"=
ot">[</span> <span class=3D"st">"lang"</span><span class=3D"ot">,</span> <s=
pan class=3D"st">"=3D"</span><span class=3D"ot">,</span> <span class=3D"st"=
>"de"</span> <span class=3D"ot">]</span></span>
<span id=3D"cb9-5"><a href=3D"https://api.vndb.org/kana#cb9-5" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"ot">,</span> <span class=3D"=
ot">[</span> <span class=3D"st">"lang"</span><span class=3D"ot">,</span> <s=
pan class=3D"st">"=3D"</span><span class=3D"ot">,</span> <span class=3D"st"=
>"fr"</span> <span class=3D"ot">]</span></span>
<span id=3D"cb9-6"><a href=3D"https://api.vndb.org/kana#cb9-6" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"ot">]</span></span>
<span id=3D"cb9-7"><a href=3D"https://api.vndb.org/kana#cb9-7" aria-hidden=
=3D"true" tabindex=3D"-1"></a><span class=3D"ot">,</span> <span class=3D"ot=
">[</span> <span class=3D"st">"olang"</span><span class=3D"ot">,</span> <sp=
an class=3D"st">"!=3D"</span><span class=3D"ot">,</span> <span class=3D"st"=
>"ja"</span> <span class=3D"ot">]</span></span>
<span id=3D"cb9-8"><a href=3D"https://api.vndb.org/kana#cb9-8" aria-hidden=
=3D"true" tabindex=3D"-1"></a><span class=3D"ot">,</span> <span class=3D"ot=
">[</span> <span class=3D"st">"release"</span><span class=3D"ot">,</span> <=
span class=3D"st">"=3D"</span><span class=3D"ot">,</span> <span class=3D"ot=
">[</span> <span class=3D"st">"and"</span></span>
<span id=3D"cb9-9"><a href=3D"https://api.vndb.org/kana#cb9-9" aria-hidden=
=3D"true" tabindex=3D"-1"></a> <span class=3D"ot">,</span> <span class=
=3D"ot">[</span> <span class=3D"st">"released"</span><span class=3D"ot">,</=
span> <span class=3D"st">"&gt;=3D"</span><span class=3D"ot">,</span> <span =
class=3D"st">"2020-01-01"</span> <span class=3D"ot">]</span></span>
<span id=3D"cb9-10"><a href=3D"https://api.vndb.org/kana#cb9-10" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"ot">,</span> <span class=
=3D"ot">[</span> <span class=3D"st">"producer"</span><span class=3D"ot">,</=
span> <span class=3D"st">"=3D"</span><span class=3D"ot">,</span> <span clas=
s=3D"ot">[</span> <span class=3D"st">"id"</span><span class=3D"ot">,</span>=
<span class=3D"st">"=3D"</span><span class=3D"ot">,</span> <span class=3D"=
st">"p30"</span> <span class=3D"ot">]</span> <span class=3D"ot">]</span></s=
pan>
<span id=3D"cb9-11"><a href=3D"https://api.vndb.org/kana#cb9-11" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"ot">]</span></span>
<span id=3D"cb9-12"><a href=3D"https://api.vndb.org/kana#cb9-12" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"ot">]</span></span>
<span id=3D"cb9-13"><a href=3D"https://api.vndb.org/kana#cb9-13" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"ot">]</span></span></code></p=
re></div>
<p>Besides the above JSON format, filters can also be represented as a
more compact string. This representation is used in the URLs for the
advanced search web interface<a href=3D"https://api.vndb.org/kana#fn2" clas=
s=3D"footnote-ref" id=3D"fnref2" role=3D"doc-noteref"><sup>2</sup></a> and =
is also accepted as
value to the <code>"filters"</code> field. Since actually working with
the compact string representation is kind of annoying, this API can
convert between the two representations, so you can freely copy filters
from the website to the API and the other way around.<a href=3D"https://api=
.vndb.org/kana#fn3" class=3D"footnote-ref" id=3D"fnref3" role=3D"doc-notere=
f"><sup>3</sup></a></p>
<p>The compact representation of the above example is
<code>"03132gen2gde2gfr3hjaN180272_0c2vQN6830u"</code> and can be seen
in action in <a href=3D"https://vndb.org/v?f=3D03132gen2gde2gfr3hjaN180272_=
0c2vQN6830u">the
web UI</a>. The following command will convert that string back into the
above JSON:</p>
<div class=3D"sourceCode" id=3D"cb10"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb10-1"><a href=3D"https://api.vndb.org=
/kana#cb10-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> https://api.vndb.org/kana/vn <span class=3D"at">--header</span> =
<span class=3D"st">'Content-Type: application/json'</span> <span class=3D"a=
t">--data</span> <span class=3D"st">'{</span></span>
<span id=3D"cb10-2"><a href=3D"https://api.vndb.org/kana#cb10-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "filters": "03132gen2=
gde2gfr3hjaN180272_0c2vQN6830u",</span></span>
<span id=3D"cb10-3"><a href=3D"https://api.vndb.org/kana#cb10-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "normalized_filters":=
true</span></span>
<span id=3D"cb10-4"><a href=3D"https://api.vndb.org/kana#cb10-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st">}'</span></span></code></=
pre></div>
<p>Note that the advanced search editing UI on the site does not support
all filter types, for unsupported filters you will see an =E2=80=9CUnrecogn=
ized
filter=E2=80=9D block. These are pretty harmless, the filter still works.</=
p>
<h4 id=3D"filter-flags">Filter flags</h4>
<p>These flags are used in the documentation below to describe a few
common filter properties.</p>
<table>
<colgroup>
<col style=3D"width: 9%">
<col style=3D"width: 90%">
</colgroup>
<thead>
<tr>
<th style=3D"text-align: right;">Flag</th>
<th style=3D"text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style=3D"text-align: right;">o</td>
<td style=3D"text-align: left;">Ordering operators (such as
<code>&gt;</code> and <code>&lt;</code>) can be used with this
filter.</td>
</tr>
<tr>
<td style=3D"text-align: right;">n</td>
<td style=3D"text-align: left;">This filter accepts <code>null</code> as
value.</td>
</tr>
<tr>
<td style=3D"text-align: right;">m</td>
<td style=3D"text-align: left;">A single entry can match multiple values.
For example, a visual novel available in both English and Japanese
matches both <code>["lang","=3D","en"]</code> and
<code>["lang","=3D","ja"]</code>.</td>
</tr>
<tr>
<td style=3D"text-align: right;">i</td>
<td style=3D"text-align: left;">Inverting or negating this filter (e.g.&nbs=
p;by
changing the operator from =E2=80=98=3D=E2=80=99 to =E2=80=98!=3D=E2=80=99 =
or from =E2=80=98&gt;=E2=80=99 to =E2=80=98&lt;=3D=E2=80=99) is not
always equivalent to inverting the selection of matching entries. This
often means that the filter implies another requirement (e.g.&nbsp;that the
information must be known in the first place), but the exact details
depend on the filter.</td>
</tr>
</tbody>
</table>
<p>Be careful with applying boolean algebra to filters with the =E2=80=98m=
=E2=80=99 or
=E2=80=98i=E2=80=99 flags, the results may be unintuitive. For example, sea=
rching for
releases matching <code>["or",["minage","=3D",0],["minage","!=3D",0]]</code=
>
will <strong>not</strong> find all releases in the database, but only
those for which the <code>minage</code> field is known. Exact semantics
regarding unknown or missing information often depends on how the filter
is implemented and may be subject to change.</p>
<h2 id=3D"post-vn">POST /vn</h2>
<p>Query visual novel entries.</p>
<div class=3D"sourceCode" id=3D"cb11"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb11-1"><a href=3D"https://api.vndb.org=
/kana#cb11-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> https://api.vndb.org/kana/vn <span class=3D"at">--header</span> =
<span class=3D"st">'Content-Type: application/json'</span> <span class=3D"a=
t">--data</span> <span class=3D"st">'{</span></span>
<span id=3D"cb11-2"><a href=3D"https://api.vndb.org/kana#cb11-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "filters": ["id", "=
=3D", "v17"],</span></span>
<span id=3D"cb11-3"><a href=3D"https://api.vndb.org/kana#cb11-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "fields": "title, ima=
ge.url"</span></span>
<span id=3D"cb11-4"><a href=3D"https://api.vndb.org/kana#cb11-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st">}'</span></span></code></=
pre></div>
<p>Accepted values for <code>"sort"</code>: <code>id</code>,
<code>title</code>, <code>released</code>, <code>rating</code>,
<code>votecount</code>, <code>searchrank</code>.</p>
<h3 id=3D"vn-filters">Filters</h3>
<table>
<colgroup>
<col style=3D"width: 22%">
<col style=3D"width: 6%">
<col style=3D"width: 70%">
</colgroup>
<thead>
<tr>
<th style=3D"text-align: left;">Name</th>
<th style=3D"text-align: left;"><a href=3D"https://api.vndb.org/kana#filter=
-flags">F</a></th>
<th style=3D"text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style=3D"text-align: left;"><code>id</code></td>
<td style=3D"text-align: left;">o</td>
<td style=3D"text-align: left;">vndbid</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>search</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">String search, matches on the VN titles,
aliases and release titles. The search algorithm is the same as used on
the site.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>lang</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Language availability.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>olang</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Original language.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>platform</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Platform availability.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>length</code></td>
<td style=3D"text-align: left;">o</td>
<td style=3D"text-align: left;">Play time estimate, integer between 1
(Very short) and 5 (Very long). This filter uses the length votes
average when available but falls back to the entries=E2=80=99
<code>length</code> field when there are no votes.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>released</code></td>
<td style=3D"text-align: left;">o,n</td>
<td style=3D"text-align: left;">Release date.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>rating</code></td>
<td style=3D"text-align: left;">o,i</td>
<td style=3D"text-align: left;">Bayesian rating, integer between 10 and
100.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>votecount</code></td>
<td style=3D"text-align: left;">o</td>
<td style=3D"text-align: left;">Integer, number of votes.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>has_description</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Only accepts a single value, integer
<code>1</code>. Can of course still be negated with the <code>!=3D</code>
operator.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>has_anime</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">See <code>has_description</code>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>has_screenshot</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">See <code>has_description</code>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>has_review</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">See <code>has_description</code>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>devstatus</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Development status, integer. See
<code>devstatus</code> field.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>tag</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Tags applied to this VN, also matches
parent tags. See below for more details.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>dtag</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Tags applied directly to this VN, does not
match parent tags. See below for details.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>anime_id</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Integer, AniDB anime identifier.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>label</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">User labels applied to this VN. Accepts a
two-element array containing a user ID and label ID. When authenticated
or if the <code>"user"</code> request parameter has been set, then it
also accepts just a label ID.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>release</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match visual novels that have at least one
release matching the given <a href=3D"https://api.vndb.org/kana#release-fil=
ters">release
filters</a>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>character</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match visual novels that have at least one
character matching the given <a href=3D"https://api.vndb.org/kana#character=
-filters">character
filters</a>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>staff</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match visual novels that have at least one
staff member matching the given <a href=3D"https://api.vndb.org/kana#staff-=
filters">staff
filters</a>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>developer</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match visual novels developed by the given
<a href=3D"https://api.vndb.org/kana#producer-filters">producer filters</a>=
.</td>
</tr>
</tbody>
</table>
<p>The <code>tag</code> and <code>dtag</code> filters accept either a
plain tag ID or a three-element array containing the tag ID, maximum
spoiler level (0, 1 or 2) and minimum tag level (number between 0 and 3,
inclusive), for example <code>["tag","=3D",["g505",2,1.2]]</code> matches
all visual novels that have a <a href=3D"https://vndb.org/g505">Donkan
Protagonist</a> with a vote of at least 1.2 at any spoiler level. If
only an ID is given, <code>0</code> is assumed for both the spoiler and
tag levels. For example, <code>["tag","=3D","g505"]</code> is equivalent
to <code>["tag","=3D",["g505",0,0]]</code>.</p>
<h3 id=3D"vn-fields">Fields</h3>
<dl>
<dt>id</dt>
<dd>
vndbid.
</dd>
<dt>title</dt>
<dd>
String, main title as displayed on the site, typically romanized from
the original script.
</dd>
<dt>alttitle</dt>
<dd>
String, can be null. Alternative title, typically the same as
<code>title</code> but in the original script.
</dd>
<dt>titles</dt>
<dd>
Array of objects, full list of titles associated with the VN, always
contains at least one title.
</dd>
<dt>titles.lang</dt>
<dd>
String, language. Each language appears at most once in the titles list.
</dd>
<dt>titles.title</dt>
<dd>
String, title in the original script.
</dd>
<dt>titles.latin</dt>
<dd>
String, can be null, romanized version of <code>title</code>.
</dd>
<dt>titles.official</dt>
<dd>
Boolean.
</dd>
<dt>titles.main</dt>
<dd>
Boolean, whether this is the =E2=80=9Cmain=E2=80=9D title for the visual no=
vel entry.
Exactly one title has this flag set in the <code>titles</code> array and
it=E2=80=99s always the title whose <code>lang</code> matches the VN=E2=80=
=99s
<code>olang</code> field. This field is included for convenience, you
can of course also use the <code>olang</code> field to grab the main
title.
</dd>
<dt>aliases</dt>
<dd>
Array of strings, list of aliases.
</dd>
<dt>olang</dt>
<dd>
String, language the VN has originally been written in.
</dd>
<dt>devstatus</dt>
<dd>
Integer, development status. 0 meaning =E2=80=98Finished=E2=80=99, 1 is =E2=
=80=98In development=E2=80=99
and 2 for =E2=80=98Cancelled=E2=80=99.
</dd>
<dt>released</dt>
<dd>
Release date, possibly null.
</dd>
<dt>languages</dt>
<dd>
Array of strings, list of languages this VN is available in. Does not
include machine translations.
</dd>
<dt>platforms</dt>
<dd>
Array of strings, list of platforms for which this VN is available.
</dd>
<dt>image</dt>
<dd>
Object, can be null.
</dd>
<dt>image.id</dt>
<dd>
String, image identifier.
</dd>
<dt>image.url</dt>
<dd>
String.
</dd>
<dt>image.dims</dt>
<dd>
Pixel dimensions of the image, array with two integer elements
indicating the width and height.
</dd>
<dt>image.sexual</dt>
<dd>
Number between 0 and 2 (inclusive), average image flagging vote for
sexual content.
</dd>
<dt>image.violence</dt>
<dd>
Number between 0 and 2 (inclusive), average image flagging vote for
violence.
</dd>
<dt>image.votecount</dt>
<dd>
Integer, number of image flagging votes.
</dd>
<dt>image.thumbnail</dt>
<dd>
String, URL to the thumbnail.
</dd>
<dt>image.thumbnail_dims</dt>
<dd>
Pixel dimensions of the thumbnail, array with two integer elements.
</dd>
<dt>length</dt>
<dd>
Integer, possibly null, rough length estimate of the VN between 1 (very
short) and 5 (very long). This field is only used as a fallback for when
there are no length votes, so you=E2=80=99ll probably want to fetch
<code>length_minutes</code> too.
</dd>
<dt>length_minutes</dt>
<dd>
Integer, possibly null, average of user-submitted play times in minutes.
</dd>
<dt>length_votes</dt>
<dd>
Integer, number of submitted play times.
</dd>
<dt>description</dt>
<dd>
String, possibly null, may contain <a href=3D"https://vndb.org/d9#4">format=
ting codes</a>.
</dd>
<dt>average</dt>
<dd>
Raw vote average, between 10 and 100, null if nobody voted (cached, may
be out of date by an hour).
</dd>
<dt>rating</dt>
<dd>
Bayesian rating, between 10 and 100, null if nobody voted (cached).
</dd>
<dt>votecount</dt>
<dd>
Integer, number of votes (cached).
</dd>
<dt>screenshots</dt>
<dd>
Array of objects, possibly empty.
</dd>
<dt>screenshots.*</dt>
<dd>
The above <code>image.*</code> fields are also available for
screenshots.
</dd>
<dt>screenshots.release.*</dt>
<dd>
Release object. All <a href=3D"https://api.vndb.org/kana#release-fields">re=
lease fields</a> can be
selected. It is very common for all screenshots of a VN to be assigned
to the same release, so the fields you select here are likely to get
duplicated several times in the response. If you want to fetch more than
just a few fields, it is more efficient to only select
<code>release.id</code> here and then grab detailed release info with a
separate request.
</dd>
<dt>relations</dt>
<dd>
Array of objects, list of VNs directly related to this entry.
</dd>
<dt>relations.relation</dt>
<dd>
String, relation type.
</dd>
<dt>relations.relation_official</dt>
<dd>
Boolean, whether this VN relation is official.
</dd>
<dt>relations.*</dt>
<dd>
All <a href=3D"https://api.vndb.org/kana#vn-fields">visual novel fields</a>=
can be selected here.
</dd>
<dt>tags</dt>
<dd>
Array of objects, possibly empty. Only directly applied tags are
returned, parent tags are not included.
</dd>
<dt>tags.rating</dt>
<dd>
Number, tag rating between 0 (exclusive) and 3 (inclusive).
</dd>
<dt>tags.spoiler</dt>
<dd>
Integer, 0, 1 or 2, spoiler level.
</dd>
<dt>tags.lie</dt>
<dd>
Boolean.
</dd>
<dt>tags.*</dt>
<dd>
All <a href=3D"https://api.vndb.org/kana#tag-fields">tag fields</a> can be =
used here. If you=E2=80=99re
fetching tags for more than a single visual novel, it=E2=80=99s usually mor=
e
efficient to only select <code>tags.id</code> here and then fetch (and
cache) further tag information as a separate request. Otherwise the same
tag info may get duplicated many times in the response.
</dd>
<dt>developers</dt>
<dd>
Array of objects. The developers of a VN are all producers with a
=E2=80=9Cdeveloper=E2=80=9D role on a release linked to the VN. You can get=
this same
information by fetching all relevant release entries, but if all you
need is the list of developers then querying this field is faster.
</dd>
<dt>developers.*</dt>
<dd>
All <a href=3D"https://api.vndb.org/kana#producer-fields">producer fields</=
a> can be used here.
</dd>
<dt>editions</dt>
<dd>
Array of objects, possibly empty.
</dd>
<dt>editions.eid</dt>
<dd>
Integer, edition identifier. This identifier is local to the visual
novel and not stable across edits of the VN entry, it=E2=80=99s only used f=
or
organizing the staff listing (see below) and has no meaning beyond that.
But this is subject to change in the future.
</dd>
<dt>editions.lang</dt>
<dd>
String, possibly null, language.
</dd>
<dt>editions.name</dt>
<dd>
String, English name / label identifying this edition.
</dd>
<dt>editions.official</dt>
<dd>
Boolean.
</dd>
<dt>staff</dt>
<dd>
Array of objects, possibly empty.
</dd>
<dt>staff.eid</dt>
<dd>
Integer, edition identifier or <em>null</em> when the staff has worked
on the =E2=80=9Coriginal=E2=80=9D version of the visual novel.
</dd>
<dt>staff.role</dt>
<dd>
String, see <code>enums.staff_role</code> in the <a href=3D"https://api.vnd=
b.org/kana#get-schema">schema JSON</a> for possible values.
</dd>
<dt>staff.note</dt>
<dd>
String, possibly null.
</dd>
<dt>staff.*</dt>
<dd>
All <a href=3D"https://api.vndb.org/kana#staff-fields">staff fields</a> can=
be used here.
</dd>
<dt>va</dt>
<dd>
Array of objects, possibly empty. Each object represents a voice actor
relation. The same voice actor may be listed multiple times for
different characters and the same character may be listed multiple times
if it has been voiced by several people.
</dd>
<dt>va.note</dt>
<dd>
String, possibly null.
</dd>
<dt>va.staff.*</dt>
<dd>
Person who voiced the character, all <a href=3D"https://api.vndb.org/kana#s=
taff-fields">staff
fields</a> can be used here.
</dd>
<dt>va.character.*</dt>
<dd>
VN character being voiced, all <a href=3D"https://api.vndb.org/kana#charact=
er-fields">character
fields</a> can be used here.
</dd>
<dt>extlinks</dt>
<dd>
Array, links to external websites. Works the same as the =E2=80=98extlinks=
=E2=80=99 <a href=3D"https://api.vndb.org/kana#release-fields">release fiel=
d</a>.
</dd>
</dl>
<h2 id=3D"post-release">POST /release</h2>
<p>Accepted values for <code>"sort"</code>: <code>id</code>,
<code>title</code>, <code>released</code>, <code>searchrank</code>.</p>
<h3 id=3D"release-filters">Filters</h3>
<table>
<colgroup>
<col style=3D"width: 24%">
<col style=3D"width: 7%">
<col style=3D"width: 68%">
</colgroup>
<thead>
<tr>
<th style=3D"text-align: left;">Name</th>
<th style=3D"text-align: left;"><a href=3D"https://api.vndb.org/kana#filter=
-flags">F</a></th>
<th style=3D"text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style=3D"text-align: left;"><code>id</code></td>
<td style=3D"text-align: left;">o</td>
<td style=3D"text-align: left;">vndbid</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>search</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">String search.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>lang</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match on available languages.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>platform</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match on available platforms.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>released</code></td>
<td style=3D"text-align: left;">o</td>
<td style=3D"text-align: left;">Release date.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>resolution</code></td>
<td style=3D"text-align: left;">o,i</td>
<td style=3D"text-align: left;">Match on the image resolution, in pixels.
Value must be a two-element integer array to which the width and height,
respectively, are compared. For example,
<code>["resolution","&lt;=3D",[640,480]]</code> matches releases with a
resolution smaller than or equal to 640x480.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>resolution_aspect</code></td>
<td style=3D"text-align: left;">o,i</td>
<td style=3D"text-align: left;">Same as the <code>resolution</code>
filter, but additionally requires that the aspect ratio matches that of
the given resolution.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>minage</code></td>
<td style=3D"text-align: left;">o,n,i</td>
<td style=3D"text-align: left;">Integer (0-18), age rating.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>medium</code></td>
<td style=3D"text-align: left;">m,n</td>
<td style=3D"text-align: left;">String.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>voiced</code></td>
<td style=3D"text-align: left;">n</td>
<td style=3D"text-align: left;">Integer, see <code>voiced</code>
field.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>engine</code></td>
<td style=3D"text-align: left;">n</td>
<td style=3D"text-align: left;">String.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>rtype</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">String, see <code>vns.rtype</code> field.
If this filter is used when nested inside a visual novel filter, then
this matches the <code>rtype</code> of the particular visual novel.
Otherwise, this matches the <code>rtype</code> of any linked visual
novel.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>extlink</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match on external links, see below for
details.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>drm</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">String, match on DRM implementation.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>image</code></td>
<td style=3D"text-align: left;">m,n</td>
<td style=3D"text-align: left;">String, see <code>images.type</code>
field.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>patch</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Integer, only accepts the value
<code>1</code>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>freeware</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">See <code>patch</code>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>uncensored</code></td>
<td style=3D"text-align: left;">i</td>
<td style=3D"text-align: left;">See <code>patch</code>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>official</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">See <code>patch</code>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>has_ero</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">See <code>patch</code>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>vn</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match releases that are linked to at least
one visual novel matching the given <a href=3D"https://api.vndb.org/kana#vn=
-filters">visual novel
filters</a>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>producer</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match releases that have at least one
producer matching the given <a href=3D"https://api.vndb.org/kana#producer-f=
ilters">producer
filters</a>.</td>
</tr>
</tbody>
</table>
<p>The <code>extlink</code> filter can be used with three types of
values:</p>
<ul>
<li>Just a site name, e.g.&nbsp;<code>["extlink","=3D","steam"]</code> matc=
hes
all releases that have a steam ID.</li>
<li>A two-element array indicating the site name and the remote
identifier, e.g. <code>["extlink","=3D",["steam",702050]]</code> to match
the Saya no Uta release on Steam. The second element can be either an
int or a string, depending on the site, but integer identifiers are also
accepted when formatted as a string.</li>
<li>A URL,
e.g.&nbsp;<code>["extlink","=3D","https://store.steampowered.com/app/702050=
/"]</code>
is equivalent to the above example.</li>
</ul>
<p>In all of the above forms, an error is returned if the site is not
known in the database or if the URL format is not recognized. The list
of supported sites and URL formats tends to change over time, see <a href=
=3D"https://api.vndb.org/kana#get-schema">GET /schema</a> for the current l=
ist of supported
sites.</p>
<p><em>Undocumented: animation</em></p>
<h3 id=3D"release-fields">Fields</h3>
<dl>
<dt>id</dt>
<dd>
vndbid.
</dd>
<dt>title</dt>
<dd>
String, main title as displayed on the site, typically romanized from
the original script.
</dd>
<dt>alttitle</dt>
<dd>
String, can be null. Alternative title, typically the same as
<code>title</code> but in the original script.
</dd>
<dt>languages</dt>
<dd>
Array of objects, languages this release is available in. There is
always exactly one language that is considered the =E2=80=9Cmain=E2=80=9D l=
anguage of
this release, which is only used to select the titles for the
<code>title</code> and <code>alttitle</code> fields.
</dd>
<dt>languages.lang</dt>
<dd>
String, language. Each language appears at most once.
</dd>
<dt>languages.title</dt>
<dd>
String, title in the original script. Can be null, in which case the
title for this language is the same as the =E2=80=9Cmain=E2=80=9D language.
</dd>
<dt>languages.latin</dt>
<dd>
String, can be null, romanized version of <code>title</code>.
</dd>
<dt>languages.mtl</dt>
<dd>
Boolean, whether this is a machine translation.
</dd>
<dt>languages.main</dt>
<dd>
Boolean, whether this language is used to determine the =E2=80=9Cmain=E2=80=
=9D title for
the release entry.
</dd>
<dt>platforms</dt>
<dd>
Array of strings.
</dd>
<dt>media</dt>
<dd>
Array of objects.
</dd>
<dt>media.medium</dt>
<dd>
String.
</dd>
<dt>media.qty</dt>
<dd>
Integer, quantity. This is <code>0</code> for media where the quantity
is unknown or where it does not make sense, like =E2=80=9Cinternet download=
=E2=80=9D.
</dd>
<dt>vns</dt>
<dd>
Array of objects, the list of visual novels this release is linked to.
</dd>
<dt>vns.rtype</dt>
<dd>
The release type for this visual novel, can be <code>"trial"</code>,
<code>"partial"</code> or <code>"complete"</code>.
</dd>
<dt>vns.*</dt>
<dd>
All <a href=3D"https://api.vndb.org/kana#vn-fields">visual novel fields</a>=
are available.
</dd>
<dt>producers</dt>
<dd>
Array of objects.
</dd>
<dt>producers.developer</dt>
<dd>
Boolean.
</dd>
<dt>producers.publisher</dt>
<dd>
Boolean.
</dd>
<dt>producers.*</dt>
<dd>
All <a href=3D"https://api.vndb.org/kana#producer-fields">producer fields</=
a> are available.
</dd>
<dt>images</dt>
<dd>
Array of objects, possibly empty.
</dd>
<dt>images.*</dt>
<dd>
All <a href=3D"https://api.vndb.org/kana#vn-fields">visual novel</a> <code>=
image.*</code> fields
are available here as well.
</dd>
<dt>images.type</dt>
<dd>
Image type, valid values are <code>"pkgfront"</code>,
<code>"pkgback"</code>, <code>"pkgcontent"</code>,
<code>"pkgside"</code>, <code>"pkgmed"</code> and <code>"dig"</code>.
</dd>
<dt>images.vn</dt>
<dd>
Visual novel ID to which this image applies, usually null. This field is
only useful for bundle releases that are linked to multiple VNs.
</dd>
<dt>images.languages</dt>
<dd>
Array of languages for which this image is valid, or null if the image
is valid for all languages assigned to this release.
</dd>
<dt>images.photo</dt>
<dd>
Boolean.
</dd>
<dt>released</dt>
<dd>
Release date.
</dd>
<dt>minage</dt>
<dd>
Integer, possibly null, age rating.
</dd>
<dt>patch</dt>
<dd>
Boolean.
</dd>
<dt>freeware</dt>
<dd>
Boolean.
</dd>
<dt>uncensored</dt>
<dd>
Boolean, can be null.
</dd>
<dt>official</dt>
<dd>
Boolean.
</dd>
<dt>has_ero</dt>
<dd>
Boolean.
</dd>
<dt>resolution</dt>
<dd>
Can either be null, the string <code>"non-standard"</code> or an array
of two integers indicating the width and height.
</dd>
<dt>engine</dt>
<dd>
String, possibly null.
</dd>
<dt>voiced</dt>
<dd>
Int, possibly null, 1 =3D not voiced, 2 =3D only ero scenes voiced, 3 =3D
partially voiced, 4 =3D fully voiced.
</dd>
<dt>notes</dt>
<dd>
String, possibly null, may contain <a href=3D"https://vndb.org/d9#4">format=
ting codes</a>.
</dd>
<dt>gtin</dt>
<dd>
JAN/EAN/UPC code, formatted as a string, possibly null.
</dd>
<dt>catalog</dt>
<dd>
String, possibly null, catalog number.
</dd>
<dt>extlinks</dt>
<dd>
Array, links to external websites. This list is equivalent to the links
displayed on the release pages on the site, so it may include redundant
entries (e.g.&nbsp;if a Steam ID is known, links to both Steam and SteamDB
are included) and links that are automatically fetched from external
resources. These extra sites are not listed in the <code>extlinks</code>
list of <a href=3D"https://api.vndb.org/kana#get-schema">the schema</a>.
</dd>
<dt>extlinks.url</dt>
<dd>
String, URL.
</dd>
<dt>extlinks.label</dt>
<dd>
String, English human-readable label for this link.
</dd>
<dt>extlinks.name</dt>
<dd>
Internal identifier of the site, intended for applications that want to
localize the label or to parse/format/extract remote identifiers. Keep
in mind that the list of supported sites, their internal names and their
ID types are subject to change, but I=E2=80=99ll try to keep things stable.
</dd>
<dt>extlinks.id</dt>
<dd>
Remote identifier for this link. Not all sites have a sensible
identifier as part of their URL format, in such cases this field is
simply equivalent to the URL.
</dd>
</dl>
<p><em>Missing: animation.</em></p>
<h2 id=3D"post-producer">POST /producer</h2>
<p>Accepted values for <code>"sort"</code>: <code>id</code>,
<code>name</code>, <code>searchrank</code>.</p>
<h3 id=3D"producer-filters">Filters</h3>
<table>
<colgroup>
<col style=3D"width: 24%">
<col style=3D"width: 7%">
<col style=3D"width: 68%">
</colgroup>
<thead>
<tr>
<th style=3D"text-align: left;">Name</th>
<th style=3D"text-align: left;"><a href=3D"https://api.vndb.org/kana#filter=
-flags">F</a></th>
<th style=3D"text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style=3D"text-align: left;"><code>id</code></td>
<td style=3D"text-align: left;">o</td>
<td style=3D"text-align: left;">vndbid</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>search</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">String search.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>lang</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Language.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>type</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Producer type, see the <code>type</code>
field below.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>extlink</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match on external links, works similar to
the <code>extlink</code> filter for <a href=3D"https://api.vndb.org/kana#re=
lease-filters">releases</a>.</td>
</tr>
</tbody>
</table>
<h3 id=3D"producer-fields">Fields</h3>
<dl>
<dt>id</dt>
<dd>
vndbid.
</dd>
<dt>name</dt>
<dd>
String.
</dd>
<dt>original</dt>
<dd>
String, possibly null, name in the original script.
</dd>
<dt>aliases</dt>
<dd>
Array of strings.
</dd>
<dt>lang</dt>
<dd>
String, primary language.
</dd>
<dt>type</dt>
<dd>
String, producer type, <code>"co"</code> for company, <code>"in"</code>
for individual and <code>"ng"</code> for amateur group.
</dd>
<dt>description</dt>
<dd>
String, possibly null, may contain <a href=3D"https://vndb.org/d9#4">format=
ting codes</a>.
</dd>
<dt>extlinks</dt>
<dd>
Array, links to external websites. Works the same as the =E2=80=98extlinks=
=E2=80=99 <a href=3D"https://api.vndb.org/kana#release-fields">release fiel=
d</a>.
</dd>
</dl>
<p><em>Missing: relations.</em></p>
<h2 id=3D"post-character">POST /character</h2>
<p>Accepted values for <code>"sort"</code>: <code>id</code>,
<code>name</code>, <code>searchrank</code>.</p>
<h3 id=3D"character-filters">Filters</h3>
<table>
<colgroup>
<col style=3D"width: 24%">
<col style=3D"width: 7%">
<col style=3D"width: 68%">
</colgroup>
<thead>
<tr>
<th style=3D"text-align: left;">Name</th>
<th style=3D"text-align: left;"><a href=3D"https://api.vndb.org/kana#filter=
-flags">F</a></th>
<th style=3D"text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style=3D"text-align: left;"><code>id</code></td>
<td style=3D"text-align: left;">o</td>
<td style=3D"text-align: left;">vndbid</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>search</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">String search.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>role</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">String, see <code>vns.role</code> field.
If this filter is used when nested inside a visual novel filter, then
this matches the <code>role</code> of the particular visual novel.
Otherwise, this matches the <code>role</code> of any linked visual
novel.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>blood_type</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">String.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>sex</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">String.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>sex_spoil</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">String.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>gender</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">String.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>gender_spoil</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">String.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>height</code></td>
<td style=3D"text-align: left;">o,n,i</td>
<td style=3D"text-align: left;">Integer, cm.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>weight</code></td>
<td style=3D"text-align: left;">o,n,i</td>
<td style=3D"text-align: left;">Integer, kg.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>bust</code></td>
<td style=3D"text-align: left;">o,n,i</td>
<td style=3D"text-align: left;">Integer, cm.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>waist</code></td>
<td style=3D"text-align: left;">o,n,i</td>
<td style=3D"text-align: left;">Integer, cm.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>hips</code></td>
<td style=3D"text-align: left;">o,n,i</td>
<td style=3D"text-align: left;">Integer, cm.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>cup</code></td>
<td style=3D"text-align: left;">o,n,i</td>
<td style=3D"text-align: left;">String, cup size.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>age</code></td>
<td style=3D"text-align: left;">o,n,i</td>
<td style=3D"text-align: left;">Integer.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>trait</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Traits applied to this character, also
matches parent traits. See below for more details.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>dtrait</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Traits applied directly to this character,
does not match parent traits. See below for details.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>birthday</code></td>
<td style=3D"text-align: left;">n</td>
<td style=3D"text-align: left;">Array of two integers, month and day. Day
may be <code>0</code> to find characters whose birthday is in a given
month.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>seiyuu</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match characters that are voiced by the
matching <a href=3D"https://api.vndb.org/kana#staff-filters">staff filters<=
/a>. Voice actor
information is actually specific to visual novels, but this filter does
not (currently) correlate against the parent entry when nested inside a
visual novel filter.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>vn</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match characters linked to visual novels
described by <a href=3D"https://api.vndb.org/kana#vn-filters">visual novel =
filters</a>.</td>
</tr>
</tbody>
</table>
<p>The <code>trait</code> and <code>dtrait</code> filters accept either
a plain trait ID or a two-element array containing the trait ID and
maximum spoiler level. These work similar to the tag filters for <a href=3D=
"https://api.vndb.org/kana#vn-filters">visual novels</a>, except that trait=
s don=E2=80=99t have a
rating.</p>
<h3 id=3D"character-fields">Fields</h3>
<dl>
<dt>id</dt>
<dd>
vndbid.
</dd>
<dt>name</dt>
<dd>
String.
</dd>
<dt>original</dt>
<dd>
String, possibly null, name in the original script.
</dd>
<dt>aliases</dt>
<dd>
Array of strings.
</dd>
<dt>description</dt>
<dd>
String, possibly null, may contain <a href=3D"https://vndb.org/d9#4">format=
ting codes</a>.
</dd>
<dt>image.*</dt>
<dd>
Object, possibly null, same sub-fields as the <code>image</code> <a href=3D=
"https://api.vndb.org/kana#vn-fields">visual novel field</a>. (Except for
<code>thumbnail</code> and <code>thumbnail_dims</code> because character
images are currently always limited to 256x300px, but that is subject to
change in the future).
</dd>
<dt>blood_type</dt>
<dd>
String, possibly null, <code>"a"</code>, <code>"b"</code>,
<code>"ab"</code> or <code>"o"</code>.
</dd>
<dt>height</dt>
<dd>
Integer, possibly null, cm.
</dd>
<dt>weight</dt>
<dd>
Integer, possibly null, kg.
</dd>
<dt>bust</dt>
<dd>
Integer, possibly null, cm.
</dd>
<dt>waist</dt>
<dd>
Integer, possibly null, cm.
</dd>
<dt>hips</dt>
<dd>
Integer, possibly null, cm.
</dd>
<dt>cup</dt>
<dd>
String, possibly null, <code>"AAA"</code>, <code>"AA"</code>, or any
single letter in the alphabet.
</dd>
<dt>age</dt>
<dd>
Integer, possibly null, years.
</dd>
<dt>birthday</dt>
<dd>
Possibly null, otherwise an array of two integers: month and day,
respectively.
</dd>
<dt>sex</dt>
<dd>
Possibly null, otherwise an array of two strings: the character=E2=80=99s
apparent (non-spoiler) sex and the character=E2=80=99s real (spoiler) sex.
Possible values are <code>null</code>, <code>"m"</code>,
<code>"f"</code>, <code>"b"</code> (meaning =E2=80=9Cboth=E2=80=9D) or <cod=
e>"n"</code>
(sexless).
</dd>
<dt>gender</dt>
<dd>
Possibly null, otherwise an array of two strings indicating the
character=E2=80=99s non-spoiler gender and the character=E2=80=99s actual (=
spoiler)
gender. Possible values are <code>null</code>, <code>"m"</code>,
<code>"f"</code>, <code>"o"</code> (non-binary) or <code>"a"</code>
(ambiguous).
</dd>
<dt>vns</dt>
<dd>
Array of objects, visual novels this character appears in. The same
visual novel may be listed multiple times with a different release; the
spoiler level and role can be different per release.
</dd>
<dt>vns.spoiler</dt>
<dd>
Integer.
</dd>
<dt>vns.role</dt>
<dd>
String, <code>"main"</code> for protagonist, <code>"primary"</code> for
main characters, <code>"side"</code> or <code>"appears"</code>.
</dd>
<dt>vns.*</dt>
<dd>
All <a href=3D"https://api.vndb.org/kana#vn-fields">visual novel fields</a>=
are available here.
</dd>
<dt>vns.release.*</dt>
<dd>
Object, usually null, specific release that this character appears in.
All <a href=3D"https://api.vndb.org/kana#release-fields">release fields</a>=
are available here.
</dd>
<dt>traits</dt>
<dd>
Array of objects, possibly empty.
</dd>
<dt>traits.spoiler</dt>
<dd>
Integer, 0, 1 or 2, spoiler level.
</dd>
<dt>traits.lie</dt>
<dd>
Boolean.
</dd>
<dt>traits.*</dt>
<dd>
All <a href=3D"https://api.vndb.org/kana#trait-fields">trait fields</a> are=
available here.
</dd>
</dl>
<p><em>Missing: gender, instances, voice actor</em></p>
<h2 id=3D"post-staff">POST /staff</h2>
<p>Unlike other database entries, staff have more than one unique
identifier. There is the main =E2=80=98staff ID=E2=80=99, which uniquely id=
entifies a
person and is what a staff page on the site represents.</p>
<p>Additionally, every staff alias also has its own unique identifier,
which is referenced from other database entries to identify which alias
was used. This identifier is generally hidden on the site and aliases do
not have their own page, but the IDs are exposed in this API in order to
facilitate linking VNs/characters to staff names.</p>
<p>This particular API queries staff <em>names</em>, not just staff
<em>entries</em>, which means that a staff entry with multiple names can
be included multiple times in the API results, once for each name they
are known as. When searching or listing staff entries, this is usually
what you want. When fetching more detailed information about specific
staff entries, this is very much not what you want. The
<code>ismain</code> filter can be used to remove this duplication and
ensure you get at most one result per staff entry, for example:</p>
<div class=3D"sourceCode" id=3D"cb12"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb12-1"><a href=3D"https://api.vndb.org=
/kana#cb12-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> https://api.vndb.org/kana/staff <span class=3D"at">--header</spa=
n> <span class=3D"st">'Content-Type: application/json'</span> <span class=
=3D"at">--data</span> <span class=3D"st">'{</span></span>
<span id=3D"cb12-2"><a href=3D"https://api.vndb.org/kana#cb12-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "filters": ["and", ["=
ismain", "=3D", 1], ["id", "=3D", "s81"] ],</span></span>
<span id=3D"cb12-3"><a href=3D"https://api.vndb.org/kana#cb12-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "fields": "lang,alias=
es{name,latin,ismain},description,extlinks{url,label}"</span></span>
<span id=3D"cb12-4"><a href=3D"https://api.vndb.org/kana#cb12-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st">}'</span></span></code></=
pre></div>
<p>Accepted values for <code>"sort"</code>: <code>id</code>,
<code>name</code>, <code>searchrank</code>.</p>
<h3 id=3D"staff-filters">Filters</h3>
<table>
<colgroup>
<col style=3D"width: 24%">
<col style=3D"width: 7%">
<col style=3D"width: 68%">
</colgroup>
<thead>
<tr>
<th style=3D"text-align: left;">Name</th>
<th style=3D"text-align: left;"><a href=3D"https://api.vndb.org/kana#filter=
-flags">F</a></th>
<th style=3D"text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style=3D"text-align: left;"><code>id</code></td>
<td style=3D"text-align: left;">o</td>
<td style=3D"text-align: left;">vndbid</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>aid</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">integer, alias identifier</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>search</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">String search.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>lang</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Language.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>gender</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Gender.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>role</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">String, can either be
<code>"seiyuu"</code> or one of the values from
<code>enums.staff_role</code> in the <a href=3D"https://api.vndb.org/kana#g=
et-schema">schema
JSON</a>. If this filter is used when nested inside a visual novel
filter, then this matches the <code>role</code> of the particular visual
novel. Otherwise, this matches the <code>role</code> of any linked
visual novel.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>extlink</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">Match on external links, works similar to
the <code>extlink</code> filter for <a href=3D"https://api.vndb.org/kana#re=
lease-filters">releases</a>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>ismain</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Only accepts a single value, integer
<code>1</code>.</td>
</tr>
</tbody>
</table>
<h3 id=3D"staff-fields">Fields</h3>
<dl>
<dt>id</dt>
<dd>
vndbid.
</dd>
<dt>aid</dt>
<dd>
Integer, alias id.
</dd>
<dt>ismain</dt>
<dd>
Boolean, whether the =E2=80=98name=E2=80=99 and =E2=80=98original=E2=80=99 =
fields represent the main
name for this staff entry.
</dd>
<dt>name</dt>
<dd>
String, possibly romanized name.
</dd>
<dt>original</dt>
<dd>
String, possibly null, name in original script.
</dd>
<dt>lang</dt>
<dd>
String, staff=E2=80=99s primary language.
</dd>
<dt>gender</dt>
<dd>
String, possibly null, <code>"m"</code> or <code>"f"</code>.
</dd>
<dt>description</dt>
<dd>
String, possibly null, may contain <a href=3D"https://vndb.org/d9#4">format=
ting codes</a>.
</dd>
<dt>extlinks</dt>
<dd>
Array, links to external websites. Works the same as the =E2=80=98extlinks=
=E2=80=99 <a href=3D"https://api.vndb.org/kana#release-fields">release fiel=
d</a>.
</dd>
<dt>aliases</dt>
<dd>
Array, list of names used by this person.
</dd>
<dt>aliases.aid</dt>
<dd>
Integer, alias id.
</dd>
<dt>aliases.name</dt>
<dd>
String, name in original script.
</dd>
<dt>aliases.latin</dt>
<dd>
String, possibly null, romanized version of =E2=80=98name=E2=80=99.
</dd>
<dt>aliases.ismain</dt>
<dd>
Boolean, whether this alias is used as =E2=80=9Cmain=E2=80=9D name for the =
staff entry.
</dd>
</dl>
<h2 id=3D"post-tag">POST /tag</h2>
<p>Accepted values for <code>"sort"</code>: <code>id</code>,
<code>name</code>, <code>vn_count</code>, <code>searchrank</code>.</p>
<h3 id=3D"filters-1">Filters</h3>
<table>
<colgroup>
<col style=3D"width: 24%">
<col style=3D"width: 7%">
<col style=3D"width: 68%">
</colgroup>
<thead>
<tr>
<th style=3D"text-align: left;">Name</th>
<th style=3D"text-align: left;"><a href=3D"https://api.vndb.org/kana#filter=
-flags">F</a></th>
<th style=3D"text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style=3D"text-align: left;"><code>id</code></td>
<td style=3D"text-align: left;">o</td>
<td style=3D"text-align: left;">vndbid</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>search</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">String search.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>category</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">String, see <code>category</code>
field.</td>
</tr>
</tbody>
</table>
<h3 id=3D"tag-fields">Fields</h3>
<dl>
<dt>id</dt>
<dd>
vndbid.
</dd>
<dt>name</dt>
<dd>
String.
</dd>
<dt>aliases</dt>
<dd>
Array of strings.
</dd>
<dt>description</dt>
<dd>
String, may contain <a href=3D"https://vndb.org/d9#4">formatting
codes</a>.
</dd>
<dt>category</dt>
<dd>
String, <code>"cont"</code> for content, <code>"ero"</code> for sexual
content and <code>"tech"</code> for technical tags.
</dd>
<dt>searchable</dt>
<dd>
Bool.
</dd>
<dt>applicable</dt>
<dd>
Bool.
</dd>
<dt>vn_count</dt>
<dd>
Integer, number of VNs this tag has been applied to, including any child
tags.
</dd>
</dl>
<p><em>Missing: some way to fetch parent/child tags. Not obvious how to
do this efficiently because tags form a DAG rather than a tree.</em></p>
<h2 id=3D"post-trait">POST /trait</h2>
<p>Accepted values for <code>"sort"</code>: <code>id</code>,
<code>name</code>, <code>char_count</code>, <code>searchrank</code>.</p>
<h3 id=3D"filters-2">Filters</h3>
<table>
<colgroup>
<col style=3D"width: 24%">
<col style=3D"width: 7%">
<col style=3D"width: 68%">
</colgroup>
<thead>
<tr>
<th style=3D"text-align: left;">Name</th>
<th style=3D"text-align: left;"><a href=3D"https://api.vndb.org/kana#filter=
-flags">F</a></th>
<th style=3D"text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style=3D"text-align: left;"><code>id</code></td>
<td style=3D"text-align: left;">o</td>
<td style=3D"text-align: left;">vndbid</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>search</code></td>
<td style=3D"text-align: left;">m</td>
<td style=3D"text-align: left;">String search.</td>
</tr>
</tbody>
</table>
<h3 id=3D"trait-fields">Fields</h3>
<dl>
<dt>id</dt>
<dd>
vndbid
</dd>
<dt>name</dt>
<dd>
String. Trait names are not necessarily self-describing, so they should
always be displayed together with their =E2=80=9Cgroup=E2=80=9D (see below)=
, which is
the top-level parent that the trait belongs to.
</dd>
<dt>aliases</dt>
<dd>
Array of strings.
</dd>
<dt>description</dt>
<dd>
String, may contain <a href=3D"https://vndb.org/d9#4">formatting
codes</a>.
</dd>
<dt>searchable</dt>
<dd>
Bool.
</dd>
<dt>applicable</dt>
<dd>
Bool.
</dd>
<dt>sexual</dt>
<dd>
Bool.
</dd>
<dt>group_id</dt>
<dd>
vndbid
</dd>
<dt>group_name</dt>
<dd>
String
</dd>
<dt>char_count</dt>
<dd>
Integer, number of characters this trait has been applied to, including
child traits.
</dd>
</dl>
<h2 id=3D"post-quote">POST /quote</h2>
<p>Query visual novel quotes.</p>
<p>Accepted values for <code>"sort"</code>: <code>id</code>,
<code>score</code>.</p>
<p>To fetch a random quote, using the same algorithm as on the website
footer:</p>
<div class=3D"sourceCode" id=3D"cb13"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb13-1"><a href=3D"https://api.vndb.org=
/kana#cb13-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> https://api.vndb.org/kana/quote <span class=3D"at">--header</spa=
n> <span class=3D"st">'Content-Type: application/json'</span> <span class=
=3D"at">--data</span> <span class=3D"st">'{</span></span>
<span id=3D"cb13-2"><a href=3D"https://api.vndb.org/kana#cb13-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "fields": "vn{id,titl=
e},character{id,name},quote",</span></span>
<span id=3D"cb13-3"><a href=3D"https://api.vndb.org/kana#cb13-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "filters": [ "random"=
, "=3D", 1 ]</span></span>
<span id=3D"cb13-4"><a href=3D"https://api.vndb.org/kana#cb13-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st">}'</span></span></code></=
pre></div>
<p>To fetch all quotes from a visual novel, ordered by score:</p>
<div class=3D"sourceCode" id=3D"cb14"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb14-1"><a href=3D"https://api.vndb.org=
/kana#cb14-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> https://api.vndb.org/kana/quote <span class=3D"at">--header</spa=
n> <span class=3D"st">'Content-Type: application/json'</span> <span class=
=3D"at">--data</span> <span class=3D"st">'{</span></span>
<span id=3D"cb14-2"><a href=3D"https://api.vndb.org/kana#cb14-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "fields": "character{=
id,name},quote,score",</span></span>
<span id=3D"cb14-3"><a href=3D"https://api.vndb.org/kana#cb14-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "filters": [ "vn", "=
=3D", [ "id", "=3D", "v5" ] ],</span></span>
<span id=3D"cb14-4"><a href=3D"https://api.vndb.org/kana#cb14-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "sort": "score",</spa=
n></span>
<span id=3D"cb14-5"><a href=3D"https://api.vndb.org/kana#cb14-5" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "reverse": true</span=
></span>
<span id=3D"cb14-6"><a href=3D"https://api.vndb.org/kana#cb14-6" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st">}'</span></span></code></=
pre></div>
<h3 id=3D"filters-3">Filters</h3>
<table>
<colgroup>
<col style=3D"width: 24%">
<col style=3D"width: 7%">
<col style=3D"width: 68%">
</colgroup>
<thead>
<tr>
<th style=3D"text-align: left;">Name</th>
<th style=3D"text-align: left;"><a href=3D"https://api.vndb.org/kana#filter=
-flags">F</a></th>
<th style=3D"text-align: left;">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style=3D"text-align: left;"><code>id</code></td>
<td style=3D"text-align: left;">o</td>
<td style=3D"text-align: left;">vndbid</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>vn</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Match quotes from the visual novel(s)
described by <a href=3D"https://api.vndb.org/kana#vn-filters">visual novel =
filters</a>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>character</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Match quotes from the characters(s)
described by <a href=3D"https://api.vndb.org/kana#character-filters">charac=
ter filters</a>.</td>
</tr>
<tr>
<td style=3D"text-align: left;"><code>random</code></td>
<td style=3D"text-align: left;"></td>
<td style=3D"text-align: left;">Only accepts a single value, integer
<code>1</code>. Matches exactly one random quote from the list of
<em>all</em> quotes with a positive score.</td>
</tr>
</tbody>
</table>
<p>The <code>random</code> filter does not really combine with any other
filters; adding other filters to the query means you may randomly get
zero results instead. You <em>could</em> select more than one random
quote by putting multiple <code>random</code> filters inside an
<code>or</code> clause, but then there=E2=80=99s still the possibility that=
you
get fewer quotes than requested, when the algorithm happens to select
the same quote multiple times. See <a href=3D"https://api.vndb.org/kana#ran=
dom">random entry</a>
for alternative strategies.</p>
<h3 id=3D"quote-fields">Fields</h3>
<dl>
<dt>id</dt>
<dd>
vndbid.
</dd>
<dt>quote</dt>
<dd>
String.
</dd>
<dt>score</dt>
<dd>
Integer.
</dd>
<dt>vn.*</dt>
<dd>
Visual novel info, all <a href=3D"https://api.vndb.org/kana#vn-fields">visu=
al novel fields</a> can
be selected here.
</dd>
<dt>character.*</dt>
<dd>
Character info, all <a href=3D"https://api.vndb.org/kana#character-fields">=
character fields</a> can
be selected here.
</dd>
</dl>
<h1 id=3D"list-management">List Management</h1>
<h2 id=3D"post-ulist">POST /ulist</h2>
<p>Fetch a user=E2=80=99s list. This API is very much like
<code>POST /vn</code>, except it requires the <code>"user"</code>
parameter to be set and it has a different response structure. All <a href=
=3D"https://api.vndb.org/kana#vn-filters">visual novel filters</a> can be u=
sed here.</p>
<p>If the user has visual novel entires on their list that have been
deleted from the database, these will not be returned through the API
even though they do show up on the website.</p>
<p>Accepted values for <code>"sort"</code>: <code>id</code>,
<code>title</code>, <code>released</code>, <code>rating</code>,
<code>votecount</code>, <code>voted</code>, <code>vote</code>,
<code>added</code>, <code>lastmod</code>, <code>started</code>,
<code>finished</code>, <code>searchrank</code>.</p>
<p>Very important example on how to fetch Yorhel=E2=80=99s top 10 voted vis=
ual
novels:</p>
<div class=3D"sourceCode" id=3D"cb15"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb15-1"><a href=3D"https://api.vndb.org=
/kana#cb15-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> https://api.vndb.org/kana/ulist <span class=3D"at">--header</spa=
n> <span class=3D"st">'Content-Type: application/json'</span> <span class=
=3D"at">--data</span> <span class=3D"st">'{</span></span>
<span id=3D"cb15-2"><a href=3D"https://api.vndb.org/kana#cb15-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "user": "u2",</span><=
/span>
<span id=3D"cb15-3"><a href=3D"https://api.vndb.org/kana#cb15-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "fields": "id, vote, =
vn.title",</span></span>
<span id=3D"cb15-4"><a href=3D"https://api.vndb.org/kana#cb15-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "filters": [ "label",=
"=3D", 7 ],</span></span>
<span id=3D"cb15-5"><a href=3D"https://api.vndb.org/kana#cb15-5" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "sort": "vote",</span=
></span>
<span id=3D"cb15-6"><a href=3D"https://api.vndb.org/kana#cb15-6" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "reverse": true,</spa=
n></span>
<span id=3D"cb15-7"><a href=3D"https://api.vndb.org/kana#cb15-7" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "results": 10</span><=
/span>
<span id=3D"cb15-8"><a href=3D"https://api.vndb.org/kana#cb15-8" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st">}'</span></span></code></=
pre></div>
<h3 id=3D"ulist-fields">Fields</h3>
<dl>
<dt>id</dt>
<dd>
Visual novel ID.
</dd>
<dt>added</dt>
<dd>
Integer, unix timestamp.
</dd>
<dt>voted</dt>
<dd>
Integer, can be null, unix timestamp of when the user voted on this VN.
</dd>
<dt>lastmod</dt>
<dd>
Integer, unix timestamp when the user last modified their list for this
VN.
</dd>
<dt>vote</dt>
<dd>
Integer, can be null, 10 - 100.
</dd>
<dt>started</dt>
<dd>
String, start date, can be null, =E2=80=9CYYYY-MM-DD=E2=80=9D format.
</dd>
<dt>finished</dt>
<dd>
String, finish date, can be null.
</dd>
<dt>notes</dt>
<dd>
String, can be null.
</dd>
<dt>labels</dt>
<dd>
Array of objects, user labels assigned to this VN. Private labels are
only listed when the user is authenticated.
</dd>
<dt>labels.id</dt>
<dd>
Integer.
</dd>
<dt>labels.label</dt>
<dd>
String.
</dd>
<dt>vn.*</dt>
<dd>
Visual novel info, all <a href=3D"https://api.vndb.org/kana#vn-fields">visu=
al novel fields</a> can
be selected here.
</dd>
<dt>releases</dt>
<dd>
Array of objects, releases of this VN that the user has added to their
list.
</dd>
<dt>releases.list_status</dt>
<dd>
Integer, 0 for =E2=80=9CUnknown=E2=80=9D, 1 for =E2=80=9CPending=E2=80=9D, =
2 for =E2=80=9CObtained=E2=80=9D, 3 for =E2=80=9COn
loan=E2=80=9D, 4 for =E2=80=9CDeleted=E2=80=9D.
</dd>
<dt>releases.*</dt>
<dd>
All <a href=3D"https://api.vndb.org/kana#release-fields">release fields</a>=
can be selected here.
</dd>
</dl>
<h2 id=3D"get-ulist_labels">GET /ulist_labels</h2>
<p>Fetch the list labels for a certain user. Accepts two query
parameters:</p>
<dl>
<dt>user</dt>
<dd>
The user ID to fetch the labels for. If the parameter is missing, the
labels for the currently authenticated user are fetched instead.
</dd>
<dt>fields</dt>
<dd>
List of fields to select. Currently only <code>count</code> may be
specified, the other fields are always selected.
</dd>
</dl>
<p>Returns a JSON object with a single key, <code>"labels"</code>, which
is an array of objects with the following members:</p>
<dl>
<dt>id</dt>
<dd>
Integer identifier of the label.
</dd>
<dt>private</dt>
<dd>
Boolean, whether this label is private. Private labels are only included
when authenticated with the <code>listread</code> permission. The
=E2=80=98Voted=E2=80=99 label (id=3D7) is always included even when private=
.
</dd>
<dt>label</dt>
<dd>
String.
</dd>
<dt>count</dt>
<dd>
Integer. The =E2=80=98Voted=E2=80=99 label may have different counts depend=
ing on
whether the user has authenticated.
</dd>
</dl>
<p>Labels with an id below 10 are the pre-defined labels and are the
same for everyone, though even pre-defined labels are excluded if they
are marked private.</p>
<p>Example: <a href=3D"https://vndb.org/u1">Multi</a> has only the default
labels.</p>
<div class=3D"sourceCode" id=3D"cb16"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb16-1"><a href=3D"https://api.vndb.org=
/kana#cb16-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> <span class=3D"st">'https://api.vndb.org/kana/ulist_labels?user=
=3Du1'</span></span></code></pre></div>
<h2 id=3D"patch-ulistid">PATCH /ulist/&lt;id&gt;</h2>
<p>Add or update a visual novel in the user=E2=80=99s list. Requires the
<code>listwrite</code> permission. The JSON body accepts the following
members:</p>
<dl>
<dt>vote</dt>
<dd>
Integer between 10 and 100.
</dd>
<dt>notes</dt>
<dd>
String.
</dd>
<dt>started</dt>
<dd>
Date.
</dd>
<dt>finished</dt>
<dd>
Date.
</dd>
<dt>labels</dt>
<dd>
Array of integers, label ids. Setting this will overwrite any existing
labels assigned to the VN with the given array.
</dd>
<dt>labels_set</dt>
<dd>
Array of label ids to add to the VN, any already existing labels will be
unaffected.
</dd>
<dt>labels_unset</dt>
<dd>
Array of label ids to remove from the VN.
</dd>
</dl>
<p>All members are be optional, missing members are not modified. A
<code>null</code> value can be used to unset a field (except for
labels).</p>
<p>The virtual labels with id 0 (=E2=80=9CNo label=E2=80=9D) and 7 (=E2=80=
=9CVoted=E2=80=9D) can not be
set. The =E2=80=9Cvoted=E2=80=9D label is automatically added/removed based=
on the
<code>vote</code> field.</p>
<p>Wonky behavior alert: this API does not verify label ids and lets you
add non-existent labels. These are not displayed on the website and not
returned by <a href=3D"https://api.vndb.org/kana#post-ulist">POST /ulist</a=
>, but they=E2=80=99re still
stored in the database and may magically show up if a label with that id
is created in the future. Don=E2=80=99t rely on this behavior, it=E2=80=99s=
a bug.</p>
<p>More wonky behavior: the website automatically unsets the other
Playing/Finished/Stalled/Dropped labels when you select one of those,
but this is not enforced server-side and the API lets you set all labels
at the same time. This is totally not a bug.</p>
<p>Example to remove the =E2=80=9CPlaying=E2=80=9D label, add the =E2=80=9C=
Finished=E2=80=9D label and
vote a 6:</p>
<div class=3D"sourceCode" id=3D"cb17"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb17-1"><a href=3D"https://api.vndb.org=
/kana#cb17-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> <span class=3D"at">-XPATCH</span> https://api.vndb.org/kana/ulis=
t/v17 <span class=3D"dt">\</span></span>
<span id=3D"cb17-2"><a href=3D"https://api.vndb.org/kana#cb17-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--header</span> <span=
class=3D"st">'Authorization: token hsoo-ybws4-j8yb9-qxkw-5obay-px8to-bfyk'=
</span> <span class=3D"dt">\</span></span>
<span id=3D"cb17-3"><a href=3D"https://api.vndb.org/kana#cb17-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--header</span> <span=
class=3D"st">'Content-Type: application/json'</span> <span class=3D"dt">\<=
/span></span>
<span id=3D"cb17-4"><a href=3D"https://api.vndb.org/kana#cb17-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--data</span> <span c=
lass=3D"st">'{"labels_unset":[1],"labels_set":[2],"vote":60}'</span></span>=
</code></pre></div>
<p>Or to remove an existing vote without affecting any of the other
fields:</p>
<div class=3D"sourceCode" id=3D"cb18"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb18-1"><a href=3D"https://api.vndb.org=
/kana#cb18-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> <span class=3D"at">-XPATCH</span> https://api.vndb.org/kana/ulis=
t/v17 <span class=3D"dt">\</span></span>
<span id=3D"cb18-2"><a href=3D"https://api.vndb.org/kana#cb18-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--header</span> <span=
class=3D"st">'Authorization: token hsoo-ybws4-j8yb9-qxkw-5obay-px8to-bfyk'=
</span> <span class=3D"dt">\</span></span>
<span id=3D"cb18-3"><a href=3D"https://api.vndb.org/kana#cb18-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--header</span> <span=
class=3D"st">'Content-Type: application/json'</span> <span class=3D"dt">\<=
/span></span>
<span id=3D"cb18-4"><a href=3D"https://api.vndb.org/kana#cb18-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--data</span> <span c=
lass=3D"st">'{"vote":null}'</span></span></code></pre></div>
<p>Slightly unintuitive behavior alert: this API <em>always</em> adds
the visual novel to the user=E2=80=99s list if it=E2=80=99s not already pre=
sent, and
that also applies to the above =E2=80=9Cremoving a vote=E2=80=9D example. U=
se <a href=3D"https://api.vndb.org/kana#delete-ulistid">DELETE</a> if you w=
ant to remove a VN from the
list.</p>
<h2 id=3D"patch-rlistid">PATCH /rlist/&lt;id&gt;</h2>
<p>Add or update a release in the user=E2=80=99s list. Requires the
<code>listwrite</code> permission. All visual novels linked to the
release are also added to the user=E2=80=99s visual novel list, if they are=
n=E2=80=99t
in the list yet. The JSON body accepts the following members:</p>
<dl>
<dt>status</dt>
<dd>
Release status, integer. See <code>releases.list_status</code> in the <a hr=
ef=3D"https://api.vndb.org/kana#ulist-fields">POST /ulist fields</a> for th=
e list of possible
values. Defaults to 0.
</dd>
</dl>
<p>Example, to mark <code>r12</code> as obtained:</p>
<div class=3D"sourceCode" id=3D"cb19"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb19-1"><a href=3D"https://api.vndb.org=
/kana#cb19-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> <span class=3D"at">-XPATCH</span> https://api.vndb.org/kana/rlis=
t/r12 <span class=3D"dt">\</span></span>
<span id=3D"cb19-2"><a href=3D"https://api.vndb.org/kana#cb19-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--header</span> <span=
class=3D"st">'Authorization: token hsoo-ybws4-j8yb9-qxkw-5obay-px8to-bfyk'=
</span> <span class=3D"dt">\</span></span>
<span id=3D"cb19-3"><a href=3D"https://api.vndb.org/kana#cb19-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--header</span> <span=
class=3D"st">'Content-Type: application/json'</span> <span class=3D"dt">\<=
/span></span>
<span id=3D"cb19-4"><a href=3D"https://api.vndb.org/kana#cb19-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--data</span> <span c=
lass=3D"st">'{"status":2}'</span></span></code></pre></div>
<h2 id=3D"delete-ulistid">DELETE /ulist/&lt;id&gt;</h2>
<p>Remove a visual novel from the user=E2=80=99s list. Returns success even=
if
the VN is not on the user=E2=80=99s list. Removing a VN also removes any
associated releases from the user=E2=80=99s list.</p>
<div class=3D"sourceCode" id=3D"cb20"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb20-1"><a href=3D"https://api.vndb.org=
/kana#cb20-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> <span class=3D"at">-XDELETE</span> https://api.vndb.org/kana/uli=
st/v17 <span class=3D"dt">\</span></span>
<span id=3D"cb20-2"><a href=3D"https://api.vndb.org/kana#cb20-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--header</span> <span=
class=3D"st">'Authorization: token hsoo-ybws4-j8yb9-qxkw-5obay-px8to-bfyk'=
</span></span></code></pre></div>
<h2 id=3D"delete-rlistid">DELETE /rlist/&lt;id&gt;</h2>
<p>Remove a release from the user=E2=80=99s list. Returns success even if t=
he
release is not on the user=E2=80=99s list. Removing a release does not remo=
ve
the associated visual novels from the user=E2=80=99s visual novel list, tha=
t
requires separate calls to <a href=3D"https://api.vndb.org/kana#delete-ulis=
tid">DELETE
/ulist/&lt;id&gt;</a>.</p>
<div class=3D"sourceCode" id=3D"cb21"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb21-1"><a href=3D"https://api.vndb.org=
/kana#cb21-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> <span class=3D"at">-XDELETE</span> https://api.vndb.org/kana/rli=
st/r12 <span class=3D"dt">\</span></span>
<span id=3D"cb21-2"><a href=3D"https://api.vndb.org/kana#cb21-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a> <span class=3D"at">--header</span> <span=
class=3D"st">'Authorization: token hsoo-ybws4-j8yb9-qxkw-5obay-px8to-bfyk'=
</span></span></code></pre></div>
<h1 id=3D"http-response-codes">HTTP Response Codes</h1>
<p>Successful responses always return either <code>200 OK</code> with a
JSON body or <code>204 No Content</code> in the case of DELETE/PATCH
requests, but errors may happen. Error response codes are typically
followed with a <code>text/plain</code> or <code>text/html</code> body.
The following is a non-exhaustive list of error codes you can expect to
see:</p>
<table>
<thead>
<tr>
<th style=3D"text-align: right;">Code</th>
<th style=3D"text-align: left;">Reason</th>
</tr>
</thead>
<tbody>
<tr>
<td style=3D"text-align: right;">400</td>
<td style=3D"text-align: left;">Invalid request body or query, the
included error message hopefully points at the problem.</td>
</tr>
<tr>
<td style=3D"text-align: right;">401</td>
<td style=3D"text-align: left;">Invalid authentication token.</td>
</tr>
<tr>
<td style=3D"text-align: right;">404</td>
<td style=3D"text-align: left;">Invalid API path or HTTP method</td>
</tr>
<tr>
<td style=3D"text-align: right;">429</td>
<td style=3D"text-align: left;">Throttled</td>
</tr>
<tr>
<td style=3D"text-align: right;">500</td>
<td style=3D"text-align: left;">Server error, usually points to a bug if
this persists</td>
</tr>
<tr>
<td style=3D"text-align: right;">502</td>
<td style=3D"text-align: left;">Server is down, should be temporary</td>
</tr>
</tbody>
</table>
<h1 id=3D"tips-troubleshooting">Tips &amp; Troubleshooting</h1>
<h2 id=3D"too-much-data-selected">=E2=80=9CToo much data selected=E2=80=9D<=
/h2>
<p>The server calculates a rough estimate of the number of JSON keys it
would generate in response to your query and throws an error if that
estimation exceeds a certain threshold, i.e.&nbsp;if the response is expect=
ed
to be rather large. This estimation is entirely based on the
<code>"fields"</code> and <code>"results"</code> parameters, so you can
work around this error by either selecting fewer fields or fewer
results.</p>
<h2 id=3D"list-of-identifiers">List of identifiers</h2>
<p>If you have a (potentially large) list of database identifiers you=E2=80=
=99d
like to fetch, it is faster and more efficient to fetch 100 entries in a
single API call than it is to make 100 separate API calls. Simply create
a filter containing the identifiers, like in the following example:</p>
<div class=3D"sourceCode" id=3D"cb22"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb22-1"><a href=3D"https://api.vndb.org=
/kana#cb22-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> https://api.vndb.org/kana/vn <span class=3D"at">--header</span> =
<span class=3D"st">'Content-Type: application/json'</span> <span class=3D"a=
t">--data</span> <span class=3D"st">'{</span></span>
<span id=3D"cb22-2"><a href=3D"https://api.vndb.org/kana#cb22-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "fields": "title",</spa=
n></span>
<span id=3D"cb22-3"><a href=3D"https://api.vndb.org/kana#cb22-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "filters": ["or"</span>=
</span>
<span id=3D"cb22-4"><a href=3D"https://api.vndb.org/kana#cb22-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> , ["id","=3D","v1"]<=
/span></span>
<span id=3D"cb22-5"><a href=3D"https://api.vndb.org/kana#cb22-5" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> , ["id","=3D","v2"]<=
/span></span>
<span id=3D"cb22-6"><a href=3D"https://api.vndb.org/kana#cb22-6" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> , ["id","=3D","v3"]<=
/span></span>
<span id=3D"cb22-7"><a href=3D"https://api.vndb.org/kana#cb22-7" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> , ["id","=3D","v4"]<=
/span></span>
<span id=3D"cb22-8"><a href=3D"https://api.vndb.org/kana#cb22-8" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> , ["id","=3D","v5"] =
],</span></span>
<span id=3D"cb22-9"><a href=3D"https://api.vndb.org/kana#cb22-9" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "results": 100</span></=
span>
<span id=3D"cb22-10"><a href=3D"https://api.vndb.org/kana#cb22-10" aria-hid=
den=3D"true" tabindex=3D"-1"></a><span class=3D"st">}'</span></span></code>=
</pre></div>
<p>Do not add more than 100 identifiers in a single query. You=E2=80=99ll
especially want to avoid sending the same list of identifiers multiple
times but with higher <code>"page"</code> numbers, see also the next
point.</p>
<h2 id=3D"pagination">Pagination</h2>
<p>While the API supports pagination through the <code>"page"</code>
parameter, this is often not the most efficient way to retrieve a large
list of entries. Results are sorted on <code>"id"</code> by default so
you can also implement pagination by filtering on this field. For
example, if the last item you=E2=80=99ve received had id <code>"v123"</code=
>,
you can fetch the next page by filtering on
<code>["id","&gt;","v123"]</code>.</p>
<p>This approach tends to not work as well when sorting on other fields,
so <code>"page"</code>-based pagination is often still the better
solution in those cases.</p>
<h2 id=3D"random">Random entry</h2>
<p>Fetching a random entry from a database is, in general, pretty
challenging to do in a performant way. Here=E2=80=99s one approach that can=
be
used with the API: first grab the highest database identifier, then
select a random number between <code>1</code> and the highest identifier
(both inclusive) and then fetch the entry with that or the nearest
increasing id, e.g.:</p>
<div class=3D"sourceCode" id=3D"cb23"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb23-1"><a href=3D"https://api.vndb.org=
/kana#cb23-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> https://api.vndb.org/kana/vn <span class=3D"at">--header</span> =
<span class=3D"st">'Content-Type: application/json'</span> <span class=3D"a=
t">--data</span> <span class=3D"st">'{</span></span>
<span id=3D"cb23-2"><a href=3D"https://api.vndb.org/kana#cb23-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "sort": "id",</span><=
/span>
<span id=3D"cb23-3"><a href=3D"https://api.vndb.org/kana#cb23-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "reverse": true,</spa=
n></span>
<span id=3D"cb23-4"><a href=3D"https://api.vndb.org/kana#cb23-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "results": 1</span></=
span>
<span id=3D"cb23-5"><a href=3D"https://api.vndb.org/kana#cb23-5" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st">}'</span></span></code></=
pre></div>
<p>Then, assuming you=E2=80=99ve randomly chosen id <code>v4567</code>:</p>
<div class=3D"sourceCode" id=3D"cb24"><pre class=3D"sourceCode sh"><code cl=
ass=3D"sourceCode bash"><span id=3D"cb24-1"><a href=3D"https://api.vndb.org=
/kana#cb24-1" aria-hidden=3D"true" tabindex=3D"-1"></a><span class=3D"ex">c=
url</span> https://api.vndb.org/kana/vn <span class=3D"at">--header</span> =
<span class=3D"st">'Content-Type: application/json'</span> <span class=3D"a=
t">--data</span> <span class=3D"st">'{</span></span>
<span id=3D"cb24-2"><a href=3D"https://api.vndb.org/kana#cb24-2" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "filters": [ "id", "&=
gt;=3D", "v4567" ],</span></span>
<span id=3D"cb24-3"><a href=3D"https://api.vndb.org/kana#cb24-3" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "fields": "title",</s=
pan></span>
<span id=3D"cb24-4"><a href=3D"https://api.vndb.org/kana#cb24-4" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st"> "results": 1</span></=
span>
<span id=3D"cb24-5"><a href=3D"https://api.vndb.org/kana#cb24-5" aria-hidde=
n=3D"true" tabindex=3D"-1"></a><span class=3D"st">}'</span></span></code></=
pre></div>
<p>The result of the first query can be cached. Additional filters can
be added to both queries if you want to narrow down the selection. This
method has a slight bias in its selection due to the presence of id
gaps, but you most likely don=E2=80=99t need perfect uniform random selecti=
on
anyway.</p>
<h1 id=3D"change-log">Change Log</h1>
<p><strong>2026-01-10</strong></p>
<ul>
<li>Add <code>image</code> filter to <a href=3D"https://api.vndb.org/kana#p=
ost-release">POST
/release</a>.</li>
</ul>
<p><strong>2025-06-02</strong></p>
<ul>
<li>Add <code>sexual</code> field to <a href=3D"https://api.vndb.org/kana#p=
ost-trait">POST
/trait</a>.</li>
</ul>
<p><strong>2025-05-02</strong></p>
<ul>
<li>Limit maximum number of filter predicates in a single request to
1000.</li>
</ul>
<p><strong>2025-04-05</strong></p>
<ul>
<li>Add <code>gender</code> field to <a href=3D"https://api.vndb.org/kana#p=
ost-character">POST
/character</a>.</li>
</ul>
<p><strong>2025-01-11</strong></p>
<ul>
<li>Add <code>gender</code> and <code>gender_spoil</code> filters to <a hre=
f=3D"https://api.vndb.org/kana#post-character">POST /character</a>.</li>
</ul>
<p><strong>2025-01-09</strong></p>
<ul>
<li>Add <code>extlink</code> filter and <code>extlinks</code> field to
<a href=3D"https://api.vndb.org/kana#post-producer">POST /producer</a>.</li=
>
</ul>
<p><strong>2025-01-07</strong></p>
<ul>
<li>Add <a href=3D"https://api.vndb.org/kana#post-quote">POST /quote</a>.</=
li>
</ul>
<p><strong>2024-09-09</strong></p>
<ul>
<li>Add <code>images</code> field to <a href=3D"https://api.vndb.org/kana#p=
ost-release">POST
/release</a>.</li>
</ul>
<p><strong>2024-07-06</strong></p>
<ul>
<li>Add <code>"n"</code> (sexless) as possible value for the
<code>sex</code> field of <a href=3D"https://api.vndb.org/kana#post-charact=
er">POST
/character</a>.</li>
</ul>
<p><strong>2024-06-05</strong></p>
<ul>
<li>Add <code>average</code> field to <a href=3D"https://api.vndb.org/kana#=
post-vn">POST
/vn</a>.</li>
</ul>
<p><strong>2024-05-23</strong></p>
<ul>
<li>Add <code>extlinks</code> field to <a href=3D"https://api.vndb.org/kana=
#post-vn">POST
/vn</a>.</li>
</ul>
<p><strong>2024-05-18</strong></p>
<ul>
<li>Add <code>va</code> field to <a href=3D"https://api.vndb.org/kana#post-=
vn">POST /vn</a>.</li>
</ul>
<p><strong>2024-05-11</strong></p>
<ul>
<li>Add <code>image{thumbnail,thumbnail_dims}</code> fields to <a href=3D"h=
ttps://api.vndb.org/kana#post-vn">POST /vn</a>. Beware: VN images can now b=
e larger than
256x400px.</li>
</ul>
<p><strong>2024-03-13</strong></p>
<ul>
<li>Add <a href=3D"https://api.vndb.org/kana#post-staff">POST /staff</a>.</=
li>
<li>Add <code>editions</code> and <code>staff</code> fields to <a href=3D"h=
ttps://api.vndb.org/kana#post-vn">POST /vn</a>.</li>
<li>Add <code>enums.staff_role</code> and <code>extlinks./staff</code>
members to <a href=3D"https://api.vndb.org/kana#get-schema">GET /schema</a>=
.</li>
</ul>
<p><strong>2023-11-20</strong></p>
<ul>
<li>Add <code>relations</code> field to <a href=3D"https://api.vndb.org/kan=
a#post-vn">POST
/vn</a>.</li>
</ul>
<p><strong>2023-08-02</strong></p>
<ul>
<li>Add <code>developers</code> field to <a href=3D"https://api.vndb.org/ka=
na#post-vn">POST
/vn</a>.</li>
</ul>
<p><strong>2023-07-11</strong></p>
<ul>
<li>Deprecated <code>popularity</code> sort options for <a href=3D"https://=
api.vndb.org/kana#post-ulist">POST /ulist</a> and <a href=3D"https://api.vn=
db.org/kana#post-vn">POST /vn</a>,
it=E2=80=99s now equivalent to sorting on the reverse of
<code>votecount</code>.</li>
<li>Deprecated <code>popularity</code> filter and field for <a href=3D"http=
s://api.vndb.org/kana#post-vn">POST /vn</a>.</li>
</ul>
<p><strong>2023-04-05</strong></p>
<ul>
<li>Add <code>searchrank</code> sort option to all endpoints that have a
<code>search</code> filter.</li>
</ul>
<p><strong>2023-03-19</strong></p>
<ul>
<li>Add <code>voiced</code>, <code>gtin</code> and <code>catalog</code>
fields to <a href=3D"https://api.vndb.org/kana#post-release">POST /release<=
/a>.</li>
</ul>
<p><strong>2023-01-17</strong></p>
<ul>
<li>Add <code>listwrite</code> permission to API tokens.</li>
<li>Add <a href=3D"https://api.vndb.org/kana#patch-ulistid">PATCH /ulist/&l=
t;id&gt;</a>.</li>
<li>Add <a href=3D"https://api.vndb.org/kana#patch-rlistid">PATCH /rlist/&l=
t;id&gt;</a>.</li>
<li>Add <a href=3D"https://api.vndb.org/kana#delete-ulistid">DELETE /ulist/=
&lt;id&gt;</a>.</li>
<li>Add <a href=3D"https://api.vndb.org/kana#delete-rlistid">DELETE /rlist/=
&lt;id&gt;</a>.</li>
</ul>
<section id=3D"footnotes" class=3D"footnotes footnotes-end-of-document" rol=
e=3D"doc-endnotes">
<hr>
<ol>
<li id=3D"fn1"><p>Yes, sorry, I know every API having its own query system
sucks, but I couldn=E2=80=99t find an existing solution that works well for
VNDB.<a href=3D"https://api.vndb.org/kana#fnref1" class=3D"footnote-back" r=
ole=3D"doc-backlink">=E2=86=A9=EF=B8=8E</a></p></li>
<li id=3D"fn2"><p>Fun fact: the web interface also accepts filters in JSON
form, but that tends to result in long and ugly URLs.<a href=3D"https://api=
.vndb.org/kana#fnref2" class=3D"footnote-back" role=3D"doc-backlink">=E2=86=
=A9=EF=B8=8E</a></p></li>
<li id=3D"fn3"><p>There is also a third representation for filters, which
the API also accepts, but I won=E2=80=99t bother you with that. It=E2=80=99=
s only useful
as an intermediate representation when converting between the JSON and
string format, which you shouldn=E2=80=99t be doing manually.<a href=3D"htt=
ps://api.vndb.org/kana#fnref3" class=3D"footnote-back" role=3D"doc-backlink=
">=E2=86=A9=EF=B8=8E</a></p></li>
</ol>
</section>
</body></html>
------MultipartBoundary--iFOSnX79r9F8KpuRTSwwVgShnV5hBx9uvFtLF8zrAZ----
Content-Type: text/css
Content-Transfer-Encoding: quoted-printable
Content-Location: cid:css-d65ec0c8-f004-4010-8603-861f49b335f5@mhtml.blink
@charset "utf-8";
body { max-width: 900px; }
td { vertical-align: top; }
header, header h1 { margin: 0px; }
@media (min-width: 1100px) {
body { margin: 0px 0px 0px 270px; }
nav { box-sizing: border-box; position: fixed; padding: 50px 20px 10px 10=
px; top: 0px; left: 0px; height: 100%; overflow: scroll; }
}
------MultipartBoundary--iFOSnX79r9F8KpuRTSwwVgShnV5hBx9uvFtLF8zrAZ----
Content-Type: text/css
Content-Transfer-Encoding: quoted-printable
Content-Location: cid:css-4278df0f-2856-4d8e-9d4c-63ab937f01cb@mhtml.blink
@charset "utf-8";
html { color: rgb(26, 26, 26); background-color: rgb(253, 253, 253); }
body { margin: 0px auto; max-width: 36em; padding: 50px; hyphens: auto; ove=
rflow-wrap: break-word; text-rendering: optimizelegibility; font-kerning: n=
ormal; }
@media (max-width: 600px) {
body { font-size: 0.9em; padding: 12px; }
h1 { font-size: 1.8em; }
}
@media print {
html { background-color: white; }
body { background-color: transparent; color: black; font-size: 12pt; }
p, h2, h3 { orphans: 3; widows: 3; }
h2, h3, h4 { break-after: avoid; }
}
p { margin: 1em 0px; }
a { color: rgb(26, 26, 26); }
a:visited { color: rgb(26, 26, 26); }
img { max-width: 100%; }
svg { height: auto; max-width: 100%; }
h1, h2, h3, h4, h5, h6 { margin-top: 1.4em; }
h5, h6 { font-size: 1em; font-style: italic; }
h6 { font-weight: normal; }
ol, ul { padding-left: 1.7em; margin-top: 1em; }
li > ol, li > ul { margin-top: 0px; }
blockquote { margin: 1em 0px 1em 1.7em; padding-left: 1em; border-left: 2px=
solid rgb(230, 230, 230); color: rgb(96, 96, 96); }
code { font-family: Menlo, Monaco, Consolas, "Lucida Console", monospace; f=
ont-size: 85%; margin: 0px; hyphens: manual; }
pre { margin: 1em 0px; overflow: auto; }
pre code { padding: 0px; overflow: visible; overflow-wrap: normal; }
.sourceCode { background-color: transparent; overflow: visible; }
hr { border-width: 1px medium medium; border-style: solid none none; border=
-color: rgb(26, 26, 26) currentcolor currentcolor; border-image: initial; h=
eight: 1px; margin: 1em 0px; }
table { margin: 1em 0px; border-collapse: collapse; width: 100%; overflow-x=
: auto; display: block; font-variant-numeric: lining-nums tabular-nums; }
table caption { margin-bottom: 0.75em; }
tbody { margin-top: 0.5em; border-top: 1px solid rgb(26, 26, 26); border-bo=
ttom: 1px solid rgb(26, 26, 26); }
th { border-top: 1px solid rgb(26, 26, 26); padding: 0.25em 0.5em; }
td { padding: 0.125em 0.5em 0.25em; }
header { margin-bottom: 4em; text-align: center; }
#TOC li { list-style: none; }
#TOC ul { padding-left: 1.3em; }
#TOC > ul { padding-left: 0px; }
#TOC a:not(:hover) { text-decoration: none; }
code { white-space: pre-wrap; }
span.smallcaps { font-variant: small-caps; }
div.columns { display: flex; gap: min(4vw, 1.5em); }
div.column { flex: 1 1 auto; overflow-x: auto; }
div.hanging-indent { margin-left: 1.5em; text-indent: -1.5em; }
ul.task-list[class] { list-style: none; }
ul.task-list li input[type=3D"checkbox"] { font-size: inherit; width: 0.8em=
; margin: 0px 0.8em 0.2em -1.6em; vertical-align: middle; }
.display.math { display: block; text-align: center; margin: 0.5rem auto; }
html { text-size-adjust: 100%; }
pre > code.sourceCode { white-space: pre; position: relative; }
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
pre > code.sourceCode > span:empty { height: 1.2em; }
.sourceCode { overflow: visible; }
code.sourceCode > span { color: inherit; text-decoration: inherit; }
div.sourceCode { margin: 1em 0px; }
pre.sourceCode { margin: 0px; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
pre > code.sourceCode { white-space: pre-wrap; }
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
}
pre.numberSource code { counter-reset: source-line 0; }
pre.numberSource code > span { position: relative; left: -4em; counter-incr=
ement: source-line 1; }
pre.numberSource code > span > a:first-child::before { content: counter(sou=
rce-line); position: relative; left: -1em; text-align: right; vertical-alig=
n: baseline; border-width: medium; border-style: none; border-color: curren=
tcolor; border-image: initial; display: inline-block; user-select: none; pa=
dding: 0px 4px; width: 4em; color: rgb(170, 170, 170); }
pre.numberSource { margin-left: 3em; border-left: 1px solid rgb(170, 170, 1=
70); padding-left: 4px; }
div.sourceCode { }
@media screen {
pre > code.sourceCode > span > a:first-child::before { text-decoration: u=
nderline; }
}
code span.al { color: rgb(255, 0, 0); font-weight: bold; }
code span.an { color: rgb(96, 160, 176); font-weight: bold; font-style: ita=
lic; }
code span.at { color: rgb(125, 144, 41); }
code span.bn { color: rgb(64, 160, 112); }
code span.bu { color: rgb(0, 128, 0); }
code span.cf { color: rgb(0, 112, 32); font-weight: bold; }
code span.ch { color: rgb(64, 112, 160); }
code span.cn { color: rgb(136, 0, 0); }
code span.co { color: rgb(96, 160, 176); font-style: italic; }
code span.cv { color: rgb(96, 160, 176); font-weight: bold; font-style: ita=
lic; }
code span.do { color: rgb(186, 33, 33); font-style: italic; }
code span.dt { color: rgb(144, 32, 0); }
code span.dv { color: rgb(64, 160, 112); }
code span.er { color: rgb(255, 0, 0); font-weight: bold; }
code span.ex { }
code span.fl { color: rgb(64, 160, 112); }
code span.fu { color: rgb(6, 40, 126); }
code span.im { color: rgb(0, 128, 0); font-weight: bold; }
code span.in { color: rgb(96, 160, 176); font-weight: bold; font-style: ita=
lic; }
code span.kw { color: rgb(0, 112, 32); font-weight: bold; }
code span.op { color: rgb(102, 102, 102); }
code span.ot { color: rgb(0, 112, 32); }
code span.pp { color: rgb(188, 122, 0); }
code span.sc { color: rgb(64, 112, 160); }
code span.ss { color: rgb(187, 102, 136); }
code span.st { color: rgb(64, 112, 160); }
code span.va { color: rgb(25, 23, 124); }
code span.vs { color: rgb(64, 112, 160); }
code span.wa { color: rgb(96, 160, 176); font-weight: bold; font-style: ita=
lic; }
------MultipartBoundary--iFOSnX79r9F8KpuRTSwwVgShnV5hBx9uvFtLF8zrAZ------
Reference in New Issue View Git Blame Copy Permalink