# Harry Potter API
> The Wizarding World of Harry Potter as an API, powered by the open PotterDB. Search hundreds of characters by name and Hogwarts house (e.g. Harry Potter → Gryffindor, Stag patronus, half-blood, with species, wand, family and titles), browse the spell book (incantations, effects, light colour and casting hand — e.g. the Patronus Charm "Expecto Patronum"), the seven novels (author, pages, release date, dedication and summary), and the potions (ingredients, effect, difficulty and side-effects — e.g. Polyjuice Potion). Filter and paginate, or fetch any item by its slug. Ideal for fan sites, trivia and quiz games, Sorting-Hat and house apps, Discord bots and any Harry Potter project.

## 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/harrypotter-api/..."
```

## Pricing
- **Free** (Free) — 11,000 calls/Mo, 2 req/s
- **Starter** ($3/Mo) — 160,000 calls/Mo, 8 req/s
- **Pro** ($10/Mo) — 700,000 calls/Mo, 20 req/s
- **Mega** ($31/Mo) — 2,850,000 calls/Mo, 50 req/s

## Endpoints

### Wizarding World

#### `GET /v1/book` — The seven books (or one by id)

**Parameters:**
- `id` (query, optional, string) — Book slug for a single book

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

**Response:**
```json
{
    "data": {
        "books": [
            {
                "id": "harry-potter-and-the-philosopher-s-stone",
                "wiki": "https://harrypotter.fandom.com/wiki/Harry_Potter_and_the_Philosopher's_Stone",
                "cover": "https://www.wizardingworld.com/images/products/books/UK/rectangle-1.jpg",
                "pages": 223,
                "title": "Harry Potter and the Philosopher's Stone",
                "author": "J. K. Rowling",
                "summary": "Harry Potter has never even heard of Hogwarts when the letters start dropping on the doormat at number four, Privet Drive. Addressed in green ink on yellowish parchment with a purple seal, they are swiftly confiscated by his grisly aunt and uncle. Then, on Harry's eleventh birthday, a great beetle-eyed giant of a man called Rubeus Hagrid bursts in with some astonishing news: Harry Potter is a wizard, and he has a place at Hogwarts School of Witchcraft and Wizardry. An incredible adventure is about to begin!",
                "dedication": "For Jessica, who loves stories, for Anne, who loved them too, and for Di, who heard this one first",
                "release_date": "1997-06-26"
            },
            {
                "id": "harry-potter-and-the-chamber-of-secrets",
                "wiki": "https://harrypotter.fandom.com/wiki/Harry_Potter_and_the_Chamber_of_Secrets",
                "cover": "https://www.wizardingworld.com/images/products/books/UK/rectangle-2.jpg",
                "pages
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/character` — Search characters by name / house

**Parameters:**
- `name` (query, optional, string) — Name search, e.g. Harry Potter Example: `Harry Potter`
- `house` (query, optional, string) — Gryffindor | Slytherin | Hufflepuff | Ravenclaw
- `id` (query, optional, string) — Slug for a single character, e.g. harry-james-potter
- `page` (query, optional, string) — Page number (default 1) Example: `1`
- `pageSize` (query, optional, string) — Page size (1-100, default 20) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/harrypotter-api/v1/character?name=Harry+Potter&page=1&pageSize=20"
```

**Response:**
```json
{
    "data": {
        "page": 1,
        "count": 2,
        "total": 2,
        "page_size": 20,
        "characters": [
            {
                "id": "unidentified-gryffindor-fifth-year-who-congratulated-harry-potter",
                "born": "Between 1 September 1976 and 31 August 1977",
                "died": null,
                "jobs": [],
                "name": "Gryffindor fifth-year who congratulated Harry Potter",
                "wiki": "https://harrypotter.fandom.com/wiki/Unidentified_Gryffindor_fifth-year_who_congratulated_Harry_Potter",
                "house": "Gryffindor",
                "image": null,
                "wands": [],
                "gender": null,
                "titles": [],
                "boggart": null,
                "species": "Human",
                "ancestry": null,
                "animagus": null,
                "patronus": null,
                "eye_color": null,
                "hair_color": null,
                "alias_names": [],
                "nationality": "British or Irish",
                "blood_status": null,
                "family_members": []
            },
            {
                "id": "unidentified-death-eater-who-was-stunned-by-harry-potter",
                "born": null,
                "died": null,
                "jobs": [],
                "name": "Unidentified Death Eater who was Stunned by Harry Potter",
                "wiki": "https://harrypotter.fandom.com/wiki/Unidentified_Death_Eater_
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/potion` — Search potions

**Parameters:**
- `name` (query, optional, string) — Potion name, e.g. Polyjuice Example: `Polyjuice`
- `id` (query, optional, string) — Potion slug
- `page` (query, optional, string) — Page number Example: `1`
- `pageSize` (query, optional, string) — Page size (1-100, default 20) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/harrypotter-api/v1/potion?name=Polyjuice&page=1&pageSize=20"
```

**Response:**
```json
{
    "data": {
        "page": 1,
        "count": 1,
        "total": 1,
        "potions": [
            {
                "id": "polyjuice-potion",
                "name": "Polyjuice Potion",
                "wiki": "https://harrypotter.fandom.com/wiki/Polyjuice_Potion",
                "image": "https://static.wikia.nocookie.net/harrypotter/images/1/1b/B2C12M2_Polyjuice_Potion_ready.jpg",
                "effect": "Allowed a human drinker to temporarily assume the form of another person",
                "inventors": null,
                "difficulty": "Advanced",
                "ingredients": "Lacewing flies (stewed for 21 days), Leeches, Powdered bicorn horn, Knotgrass, Fluxweed (picked at full moon), Shredded boomslang skin, A bit of the person one wanted to turn into (typically hair or toenails), Standard potioning water",
                "side_effects": "Attempts to transform into animals or part-humans would not reverse automatically",
                "characteristics": "Thick and mud-like, Bubbles slowly, Taste and colour varied depending on the person being turned into"
            }
        ],
        "page_size": 20
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:31.648Z",
        "request_id": "5302d4a0-3b26-46fc-8dc5-b8ff40171c9f"
    },
    "status": "ok",
    "message": "Potion retrieved",
    "success": true
}
```

#### `GET /v1/spell` — Search spells

**Parameters:**
- `name` (query, optional, string) — Spell name, e.g. Patronus Example: `Patronus`
- `id` (query, optional, string) — Spell slug
- `page` (query, optional, string) — Page number Example: `1`
- `pageSize` (query, optional, string) — Page size (1-100, default 20) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/harrypotter-api/v1/spell?name=Patronus&page=1&pageSize=20"
```

**Response:**
```json
{
    "data": {
        "page": 1,
        "count": 1,
        "total": 1,
        "spells": [
            {
                "id": "patronus-charm",
                "hand": null,
                "name": "Patronus Charm",
                "wiki": "https://harrypotter.fandom.com/wiki/Patronus_Charm",
                "image": "https://static.wikia.nocookie.net/harrypotter/images/f/fe/Patronus_PM_SilverStagPatronus_MomentIllust.jpg",
                "light": "Silver",
                "effect": "Conjured a spirit guardian",
                "creator": null,
                "category": "Charm",
                "incantation": "Expecto Patronum(ex-PEK-toh pa-TRO-num)"
            }
        ],
        "page_size": 20
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:31.737Z",
        "request_id": "07b97023-bf8c-4075-ae6b-564799b46ab8"
    },
    "status": "ok",
    "message": "Spell retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Houses & usage notes

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

**Response:**
```json
{
    "data": {
        "note": "The Wizarding World of Harry Potter. /v1/character = search characters by name (and house=Gryffindor|Slytherin|Hufflepuff|Ravenclaw) or fetch by id — with species, blood status, patronus, wand, family and more; /v1/spell = search spells (incantation, effect, light); /v1/book = the seven books; /v1/potion = search potions (ingredients, effect, difficulty). Add page & pageSize to paginate; ids are lowercase-hyphenated slugs.",
        "houses": [
            "Gryffindor",
            "Slytherin",
            "Hufflepuff",
            "Ravenclaw"
        ],
        "source": "PotterDB (api.potterdb.com)",
        "endpoints": [
            "/v1/character",
            "/v1/spell",
            "/v1/book",
            "/v1/potion",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:31.802Z",
        "request_id": "8def8def-4ed6-4af9-9329-2c8ebd2d385b"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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