HP-API (Characters)
Free Harry Potter character API with no key: full character records with house, wand composition, patronus, ancestry and actor names. Filter by house. Tested example included.
Endpoint tested and returned HTTP 200 on 2026-08-21
What is the HP-API (Characters)?
HP-API is a free, key-free REST API serving detailed Harry Potter character records. Each entry includes house, birth date, ancestry, wand wood, core and length, patronus, whether the character is a wizard, and the actor who played them, with dedicated endpoints for filtering by house or listing staff and students.
Where most Harry Potter APIs stop at names and houses, HP-API models the details fans actually care about. The `wand` object breaks down wood, core and length; there are separate fields for `ancestry`, `patronus`, `eyeColour` and `hairColour`; and `actor` plus `alternate_actors` connect the books to the films. That depth is what makes it a better fit for a real fan project than a bare character list.
The house filter is built into the path — `/characters/house/gryffindor` — rather than being a query parameter, which makes the four house endpoints trivially cacheable and is the pattern most sample projects use. Companion paths cover students and staff. One thing to plan for: the API runs on a free Render instance that sleeps when idle, so the first request after a quiet period may take several seconds to answer.
Quick facts
- Base URL
https://hp-api.onrender.com/api- Authentication
- No API key or account. Open source and community-maintained.
- Rate limit
- No published limit. The dataset is static, so cache it and you will rarely call twice.
- Pricing
- Free.
- CORS
- Enabled — callable directly from browser JavaScript
- Official docs
- Read the docs
How to use the HP-API (Characters)
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. List every Gryffindor character
GET https://hp-api.onrender.com/api/characters/house/gryffindor
curl 'https://hp-api.onrender.com/api/characters/house/gryffindor'const res = await fetch("https://hp-api.onrender.com/api/characters/house/gryffindor");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);import requests
res = requests.get("https://hp-api.onrender.com/api/characters/house/gryffindor", timeout=20)
res.raise_for_status()
print(res.json())[
{
"id": "9e3f7ce4-b9a7-4244-b709-dae5c1f1d4a8",
"name": "Harry Potter",
"alternate_names": [
"The Boy Who Lived",
"The Chosen One",
"Undesirable No. 1",
"Potty"
],
"species": "human",
"gender": "male",
"house": "Gryffindor",
"dateOfBirth": "31-07-1980",
"yearOfBirth": 1980,
"wizard": true,
"ancestry": "half-blood",
"eyeColour": "green",
"hairColour": "black",
"wand": {
"wood": "holly",
"core": "phoenix tail feather",
"length": 11
},
"patronus": "stag",
"hogwartsStudent": true,
"hogwartsStaff": false,
"actor": "Daniel Radcliffe",
"alternate_actors": [],
"alive": true,
"image": "https://ik.imagekit.io/hpapi/harry.jpg"
},
{
"id": "4c7e6819-a91a-45b2-a454-f931e4a7cce3",
"name": "Hermione Granger",
"alternate_names": [
"Hermy",
"Know-it-all",
"Miss Grant",
"Herm-own-ninny"
],
"species": "human",
"gender": "female",
"house": "Gryffindor",
"dateOfBirth": "19-09-1979",
"yearOfBirth": 1979,
"wizard": true,
"ancestry": "muggleborn",
"eyeColour": "brown",
"hairColour": "brown",
"wand": {
"wood": "vine",
"core": "dragon heartstring",
"length": 10.75
},
"patronus": "otter",
"hogwartsStudent": true,
"hogwartsStaff": false,
"actor": "Emma Watson",
"alternate_actors": [],
"alive": true,
"image": "https://ik.imagekit.io/hpapi/hermione.jpeg"
},
{
"id": "c3b1f9a5-b87b-48bf-b00d-95b093ea6390",
"name": "Ron Weasley",Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
house | path segment | Optional | Filter by house on `/characters/house/{house}`: `gryffindor`, `slytherin`, `ravenclaw` or `hufflepuff`. Lowercase. gryffindor |
(students) | path segment | Optional | The `/characters/students` path returns only students. |
(staff) | path segment | Optional | The `/characters/staff` path returns only Hogwarts staff. |
id | path segment | Optional | Fetch one character by UUID via `/character/{id}`. |
(spells) | path segment | Optional | The `/spells` path returns the spell list instead of characters. |
Response fields
idstring- UUID for the character — stable, unlike the name.
name / alternate_namesstring, array- Canonical name plus every epithet the character is known by.
housestring- Hogwarts house. Empty string for characters who never attended, so check for that rather than assuming null.
wandobject- Wand composition with `wood`, `core` and `length`. Fields are empty strings when unknown, not null.
patronusstring- Patronus form, empty when the character has none or it was never established.
ancestrystring- `pure-blood`, `half-blood`, `muggleborn` or empty.
actor / alternate_actorsstring, array- Film casting, including actors who played the character at different ages.
imagestring- Character portrait URL. Empty for minor characters, so guard before rendering.
What you can build with the HP-API (Characters)
- Build a character browser or house-sorting fan app
- Provide a rich dataset for a React or Vue tutorial with real filtering
- Add character lookup to a Harry Potter Discord bot
- Create a wand or patronus quiz driven by real data
Common errors and how to fix them
Slow first request
The free Render instance sleeps when idle.
Fix: Expect several seconds on a cold start. Cache the response — the dataset is static — and do not block a page render on the first call.
404
Unknown house name or misspelled path.
Fix: House names are lowercase in the path. The characters path is plural (`/characters`) while the single-record path is singular (`/character/{id}`).
Empty strings instead of null
Not an error — unknown values are empty strings.
Fix: Check for `""` as well as null. A falsy check covers both, but a strict null check will silently pass empty strings through to your UI.
HP-API (Characters) — frequently asked questions
Is the Harry Potter characters API free?
Yes, free with no API key or account. It is open source and community-maintained, hosted on a free tier.
What character details does it include?
House, birth date, ancestry, patronus, eye and hair colour, whether the character is a wizard, full wand composition (wood, core and length) and the actors who played them across the films.
How do I filter characters by house?
The filter is part of the path rather than a query parameter: request `/characters/house/gryffindor` in lowercase. There are also `/characters/students` and `/characters/staff` paths.
Why are some fields empty strings instead of null?
The dataset uses empty strings for unknown values throughout — houses, wands, patronuses. A strict null check will pass those through to your interface, so test for falsiness or for the empty string explicitly.
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 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.
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.
HP-API (Characters) 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.