# VNDB Visual Novel API
> The Visual Novel Database (VNDB) as an API — clean JSON, no key. Search and look up visual novels with their titles, release dates, languages, platforms, play length, Bayesian rating and vote count, description, cover image, developers and genre/theme tags (spoiler tags filtered out). Search and open characters with their original name, aliases, description, sex, age, blood type and the visual novels they appear in, and search and open producers and developers. Plus live database statistics. Live data straight from vndb.org, the definitive visual-novel database. A distinct medium from anime and manga — ideal for visual-novel trackers, discovery and recommendation apps, wikis and otaku tools. 7 data endpoints. Authenticated with an x-oanor-key; fair-use rate limits per plan.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/vndb-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 5 req/s
- **Starter** ($6/Mo) — 45,000 calls/Mo, 15 req/s
- **Pro** ($25/Mo) — 250,000 calls/Mo, 30 req/s
- **Mega** ($85/Mo) — 1,100,000 calls/Mo, 80 req/s

## Endpoints

### Visual Novels

#### `GET /v1/search/vn` — Search visual novels

**Parameters:**
- `query` (query, required, string) — Title to search Example: `steins;gate`
- `limit` (query, optional, string) — Max results (1–50) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vndb-api/v1/search/vn?query=steins%3Bgate&limit=20"
```

**Response:**
```json
{
    "data": {
        "more": false,
        "count": 10,
        "query": "steins;gate",
        "visual_novels": [
            {
                "id": "v2002",
                "url": "https://vndb.org/v2002",
                "tags": [
                    "Blind Choices",
                    "Chuunibyou Protagonist",
                    "One True End",
                    "Suspense",
                    "Modern Day Akihabara",
                    "Male Protagonist",
                    "Group of Friends",
                    "Protagonist with Voice Acting",
                    "Built-in Encyclopedia",
                    "Scientist Heroine",
                    "Thriller",
                    "Genius Heroine",
                    "Inventor Heroine",
                    "Date Display",
                    "Tsundere Heroine"
                ],
                "image": "https://t.vndb.org/cv/19/77819.jpg",
                "title": "STEINS;GATE",
                "length": "Long (30–50h)",
                "rating": 90.2,
                "released": "2009-10-15",
                "alt_title": null,
                "languages": [
                    "cs",
                    "de",
                    "en",
                    "es",
                    "hu",
                    "it",
                    "ja",
                    "ko",
                    "pl",
                    "pt-br",
                    "ru",
                    "tr",
                    "vi",
              
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/vn` — Visual novel detail

**Parameters:**
- `id` (query, required, string) — VNDB id (e.g. v2002) Example: `v2002`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vndb-api/v1/vn?id=v2002"
```

**Response:**
```json
{
    "data": {
        "visual_novel": {
            "id": "v2002",
            "url": "https://vndb.org/v2002",
            "tags": [
                "Blind Choices",
                "Chuunibyou Protagonist",
                "One True End",
                "Suspense",
                "Modern Day Akihabara",
                "Male Protagonist",
                "Group of Friends",
                "Protagonist with Voice Acting",
                "Built-in Encyclopedia",
                "Scientist Heroine",
                "Thriller",
                "Genius Heroine",
                "Inventor Heroine",
                "Date Display",
                "Tsundere Heroine"
            ],
            "image": "https://t.vndb.org/cv/19/77819.jpg",
            "title": "STEINS;GATE",
            "length": "Long (30–50h)",
            "rating": 90.2,
            "released": "2009-10-15",
            "alt_title": null,
            "languages": [
                "cs",
                "de",
                "en",
                "es",
                "hu",
                "it",
                "ja",
                "ko",
                "pl",
                "pt-br",
                "ru",
                "tr",
                "vi",
                "zh-Hans",
                "zh-Hant"
            ],
            "platforms": [
                "win",
                "ios",
                "and",
                "psp",
                "ps3",
                "ps4",
                "psv",
     
…(truncated, see openapi.json for full schema)
```

### Characters

#### `GET /v1/character` — Character detail

**Parameters:**
- `id` (query, required, string) — Character id (e.g. c44) Example: `c44`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vndb-api/v1/character?id=c44"
```

**Response:**
```json
{
    "data": {
        "character": {
            "id": "c44",
            "age": null,
            "sex": "m",
            "url": "https://vndb.org/c44",
            "vns": [
                {
                    "id": "v11",
                    "role": "side",
                    "title": "Fate/stay night"
                },
                {
                    "id": "v50",
                    "role": "side",
                    "title": "Fate/hollow ataraxia"
                }
            ],
            "name": "Kuzuki Souichirou",
            "image": "https://t.vndb.org/ch/46/46.jpg",
            "height": 180,
            "aliases": [],
            "original": "葛木 宗一郎",
            "blood_type": null,
            "description": "Kuzuki Souichirou is the strict homeroom instructor of [url=/c34]Rin's[/url] class. He primarily lectures on World History, though he also holds classes in Ethics. A well-built man with angular glasses, Kuzuki is well respected among staff and students, but he is widely regarded as austere and impersonal.\n\n[Edited from [url=http://en.wikipedia.org/wiki/List_of_Fate/stay_night_characters]Wikipedia[/url]]"
        }
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:51.863Z",
        "request_id": "b8246d50-7dc5-4c52-858a-1cd266929cf1"
    },
    "status": "ok",
    "message": "Character retrieved successfully",
    "success": true
}
```

#### `GET /v1/search/characters` — Search characters

**Parameters:**
- `query` (query, required, string) — Character name Example: `saber`
- `limit` (query, optional, string) — Max results Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vndb-api/v1/search/characters?query=saber&limit=20"
```

**Response:**
```json
{
    "data": {
        "more": true,
        "count": 20,
        "query": "saber",
        "characters": [
            {
                "id": "c33",
                "age": null,
                "sex": "f",
                "url": "https://vndb.org/c33",
                "vns": [
                    {
                        "id": "v11",
                        "role": "primary",
                        "title": "Fate/stay night"
                    },
                    {
                        "id": "v50",
                        "role": "primary",
                        "title": "Fate/hollow ataraxia"
                    },
                    {
                        "id": "v666",
                        "role": "appears",
                        "title": "Twinkle ☆ Crusaders"
                    },
                    {
                        "id": "v14554",
                        "role": "primary",
                        "title": "Fate/Zero The Adventure"
                    }
                ],
                "name": "Saber",
                "image": "https://t.vndb.org/ch/34/34.jpg",
                "height": 154,
                "aliases": [
                    "Altria Pendragon",
                    "アルトリア・ペンドラゴン",
                    "Artoria Pendragon"
                ],
                "original": "セイバー",
                "blood_type": "o",
                "description": "Saber is [url=/c15]Shirou's[/url] Servant. Loyal, i
…(truncated, see openapi.json for full schema)
```

### Producers

#### `GET /v1/producer` — Producer detail

**Parameters:**
- `id` (query, required, string) — Producer id (e.g. p37) Example: `p37`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vndb-api/v1/producer?id=p37"
```

**Response:**
```json
{
    "data": {
        "producer": {
            "id": "p37",
            "url": "https://vndb.org/p37",
            "lang": "ja",
            "name": "Alchemist Co., Ltd.",
            "type": "co",
            "aliases": [],
            "original": "株式会社アルケミスト",
            "description": "Filed for bankruptcy on April 1st, 2016 and dissolved on January 18, 2017."
        }
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:52.176Z",
        "request_id": "01527f4d-bc93-4fe0-8a7a-8db044635a26"
    },
    "status": "ok",
    "message": "Producer retrieved successfully",
    "success": true
}
```

#### `GET /v1/search/producers` — Search producers/developers

**Parameters:**
- `query` (query, required, string) — Producer name Example: `key`
- `limit` (query, optional, string) — Max results Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vndb-api/v1/search/producers?query=key&limit=20"
```

**Response:**
```json
{
    "data": {
        "more": true,
        "count": 20,
        "query": "key",
        "producers": [
            {
                "id": "p24",
                "url": "https://vndb.org/p24",
                "lang": "ja",
                "name": "Key",
                "type": "co",
                "aliases": [
                    "キー"
                ],
                "original": null,
                "description": "Key is a Japanese visual novel studio known for making dramatic and plot-oriented titles. It was formed on July 21, 1998, as a brand under the publisher Visual Arts, and is located in Kita, Osaka.\n\nCo-founder Jun Maeda is a prominent figure in the brand, having contributed to the planning, scenario, and music composition in the majority of Key's visual novels. Na-Ga, Key's main artist, mainly worked with background art in earlier games, but with Key's sixth game Little Busters! (2007) was given the position of co-art director with former Key artist Itaru Hinoue. Shinji Orito, Key's main composer and another co-founder, has composed music for the majority of Key's titles.\n\nKey has been an active participant at the Comiket convention since Comiket 57 in 1999, where they sold Kanon-related products; Key's latest appearance at Comiket was at Comiket 99 in 2021. In 2001, Visual Arts created the record label Key Sounds Label to release music albums and singles with music related to Key's visual novels. Between 2007 and 2010, Key produced an Internet radio 
…(truncated, see openapi.json for full schema)
```

### Reference

#### `GET /v1/stats` — Database statistics

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vndb-api/v1/stats"
```

**Response:**
```json
{
    "data": {
        "stats": {
            "vn": 63444,
            "tags": 3003,
            "chars": 165073,
            "staff": 52219,
            "traits": 3321,
            "releases": 149510,
            "producers": 28748
        }
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:52.438Z",
        "request_id": "7aeb32dc-0116-4d56-b6ff-d2981c1e97cc"
    },
    "status": "ok",
    "message": "Stats retrieved successfully",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/vndb-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "service": "vndb-api",
        "endpoints": {
            "GET /v1/vn": "Visual novel detail by id (e.g. v2002).",
            "GET /v1/meta": "This document.",
            "GET /v1/stats": "Database statistics.",
            "GET /v1/producer": "Producer detail by id (e.g. p37).",
            "GET /v1/character": "Character detail by id (e.g. c44).",
            "GET /v1/search/vn": "Search visual novels.",
            "GET /v1/search/producers": "Search producers/developers.",
            "GET /v1/search/characters": "Search characters."
        },
        "description": "VNDB: search and look up visual novels, characters and producers/developers, plus database stats. Real live data, no key."
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:52.521Z",
        "request_id": "1fe47d84-fe39-47d2-bd0b-27dbb4467020"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/vndb-api
OpenAPI spec: https://www.oanor.com/api/vndb-api/openapi.json