PotterDB API

PotterDB is a free JSON:API over the Harry Potter universe: books, chapters, characters, movies, potions and spells, with filtering, sorting and pagination. Live example included.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the PotterDB API?

PotterDB is a free, key-free REST API covering the Harry Potter universe. It serves books, chapters, characters, movies, potions and spells as a JSON:API document with filter, sort and pagination support, so you can query the dataset rather than downloading all of it.

Most Harry Potter APIs are a single flat list of characters. PotterDB is the one with an actual relational dataset behind it: books link to their chapters, characters carry house, wand, patronus and blood-status attributes, and potions and spells are separate collections with their own effects and incantations. That makes it the right choice when your project needs to join records rather than just render a grid of faces.

It also speaks JSON:API properly, which is unusual for a fan project and quietly useful to practise against. Every record arrives as an object with `id`, `type`, `attributes` and `relationships`, filters are written as `filter[name_cont]=potter` rather than ad-hoc query names, and paging uses `page[size]` and `page[number]`. If you have only ever consumed bespoke JSON shapes, an afternoon here is a decent introduction to a specification that a lot of Ruby and Ember back ends still emit.

Quick facts

Base URL: https://api.potterdb.com/v1
Authentication: No API key and no account. The project asks only that you do not hammer it.
Rate limit: No published limit. The dataset barely changes, so cache responses for a day and you will never come near one.
Pricing: Free. Community-run and open source.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the PotterDB API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Fetch the first two books

GET https://api.potterdb.com/v1/books?page%5Bsize%5D=2

curl

curl 'https://api.potterdb.com/v1/books?page%5Bsize%5D=2'

JavaScript (fetch)

const res = await fetch("https://api.potterdb.com/v1/books?page%5Bsize%5D=2");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://api.potterdb.com/v1/books?page%5Bsize%5D=2", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "data": [
    {
      "id": "9e74d8ae-6164-4a48-9b89-763abb0af154",
      "type": "book",
      "attributes": {
        "slug": "harry-potter-and-the-philosopher-s-stone",
        "author": "J. K. Rowling",
        "cover": "https://www.wizardingworld.com/images/products/books/UK/rectangle-1.jpg",
        "dedication": "For Jessica, who loves stories, for Anne, who loved them too, and for Di, who heard this one first",
        "pages": 223,
        "release_date": "1997-06-26",
        "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!",
        "title": "Harry Potter and the Philosopher's Stone",
        "wiki": "https://harrypotter.fandom.com/wiki/Harry_Potter_and_the_Philosopher's_Stone"
      },
      "relationships": {
        "chapters": {
          "data": [
            {
              "id": "47a6f8c3-098a-414d-b255-180ce9cebddf",
              "type": "chapter"
            },
            {
              "id": "f596c58d-a3ff-4537-bc55-47d4520713d1",
              "type": "chapter"
            },
            {
              "id": "f6c398b4-13c2-42d7-bf08-d2c0ee9b7368",
              "type": "chapter

Parameters

Parameter	Type	Required	Description
`resource`	path segment	Required	One of `books`, `characters`, `movies`, `potions` or `spells`. Chapters hang off a book: `/books/{slug}/chapters`. `books`
`page[size]`	integer	Optional	Records per page. Defaults to 25. `2`
`page[number]`	integer	Optional	Which page to return, 1-based. `3`
`filter[name_cont]`	string	Optional	Substring match on the name. The `_cont` suffix is Ransack syntax — `_eq`, `_start` and `_end` also work. `potter`
`filter[house_eq]`	string	Optional	Exact match on a character's house. `Gryffindor`
`sort`	string	Optional	Attribute to sort by. Prefix with `-` to reverse. `-release_date`

Response fields

data[].idstring (uuid): Stable UUID for the record. Use this, not the array index.
data[].typestring: Record type: `book`, `character`, `movie`, `potion` or `spell`.
data[].attributes.slugstring: URL-safe identifier, which is what the chapters sub-resource expects.
data[].attributesobject: All the actual content. For books: title, author, summary, dedication, pages, release_date, cover. For characters: house, wand, patronus, blood_status, born, died.
data[].relationshipsobject: Links to related records, so a book carries the id of every one of its chapters.
meta.paginationobject: Current page, total records and total pages, returned alongside the data rather than in headers.

What you can build with the PotterDB API

Build a Hogwarts character browser with house and wand filters
Practise consuming a real JSON:API document, including filters and relationships
Seed a quiz app with spells, potions and their effects
Add a lore lookup command to a Discord or Slack bot
Teach pagination against a dataset small enough to reason about end to end

Common errors and how to fix them

404

Unknown collection or slug.

Fix: Collections are plural and lowercase. Chapters are not top-level — request them as `/books/{slug}/chapters`.

Filter appears to be ignored

The filter name is missing its matcher suffix.

Fix: PotterDB uses Ransack matchers, so it is `filter[name_cont]`, not `filter[name]`. Without the suffix the parameter is silently dropped.

Empty `data` array

The filter matched nothing, which is not an error.

Fix: Check spelling and case of the value; `house_eq` is an exact match and will not find `gryffindor` in lowercase.

PotterDB API — frequently asked questions

Is the PotterDB API free and does it need a key?

It is free and needs no key or account. It is a community project, released open source, and the only request is that you cache rather than poll it hard.

How is PotterDB different from the other Harry Potter APIs?

Most alternatives serve a flat character list. PotterDB carries books, chapters, movies, potions and spells as separate related collections, and exposes filtering, sorting and pagination, so you can query the data instead of downloading everything and filtering client-side.

Why does the response look different from normal JSON?

It follows the JSON:API specification, so each record is wrapped in `id`, `type`, `attributes` and `relationships` rather than being a flat object. The content-type is `application/vnd.api+json` for the same reason.

Can I call PotterDB from the browser?

Yes. It sends a permissive `Access-Control-Allow-Origin` header, so `fetch()` from front-end JavaScript works with no proxy and there is no key to leak.

Tools that pair with this API

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

JSON Path Finder

Evaluate a dot/bracket path against your JSON and list every leaf path for discovery. Free online JSON path finder that runs 100% in your browser.

JSON to CSV Converter

Convert a JSON array of objects to CSV online. Automatic column headers from the union of all keys, delimiter choice and proper quoting — all in-browser.

PotterDB is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.