# Harry Potter API

> Look up characters and spells from the wizarding world using the free, keyless Harry Potter API (HP-API): search or page through 400+ characters with their house, species, ancestry, patronus, wand, and the actor who played them, narrow to Hogwarts students, staff, or a single house, and search 70+ spells by incantation or by what they do. No account or API key required. Disclaimer: this is an independent integration with the community-run HP-API (hp-api.onrender.com). It is not affiliated with, endorsed by, or sponsored by J.K. Rowling, Warner Bros., or Pottermore; Harry Potter and all related names, characters, and trademarks are the property of their respective owners.

App · Film, TV & Fandom · 8 actions. Web page: https://docs.lodol.com/docs/integrations/harry-potter-api

## Actions

### Get a character

Get a single character by their API id, the UUID any list or search action returns as 'id'. Searching by name first is the usual way to find that id.

**Inputs**

- Character ID (`character_id`, text, required): The character's API id, such as '9e3f7ce4-b9a7-4244-b709-dae5c1f1d4a8' (Harry Potter). Read it off the 'id' field of a list or search result.

**Outputs**

- `character` (object): The matching character.

**Example output**

```json
{
  "character": {
    "actor": "Daniel Radcliffe",
    "alive": true,
    "alternate_actors": [],
    "alternate_names": [
      "The Boy Who Lived",
      "The Chosen One",
      "Undesirable No. 1",
      "Potty"
    ],
    "ancestry": "half-blood",
    "dateOfBirth": "31-07-1980",
    "eyeColour": "green",
    "gender": "male",
    "hairColour": "black",
    "hogwartsStaff": false,
    "hogwartsStudent": true,
    "house": "Gryffindor",
    "id": "9e3f7ce4-b9a7-4244-b709-dae5c1f1d4a8",
    "image": "https://ik.imagekit.io/hpapi/harry.jpg",
    "name": "Harry Potter",
    "patronus": "stag",
    "species": "human",
    "wand": {
      "core": "phoenix tail feather",
      "length": 11,
      "wood": "holly"
    },
    "wizard": true,
    "yearOfBirth": 1980
  }
}
```

### List characters

List every character in the Harry Potter API: witches, wizards, muggles, ghosts, and magical creatures. Each record includes their house, species, ancestry, patronus, wand, the actor who played them, and a portrait URL. Use Limit and Offset to take a slice of the 400+ records.

**Inputs**

- Limit (`limit`, number): How many records to return at most (defaults to all of them). The API sends the whole collection in one response, so this trims it afterwards. At least 1.
- Offset (`offset`, number): How many records to skip before returning any (defaults to none). Pair it with Limit to walk a large collection a chunk at a time. At least 0.

**Outputs**

- `characters` (list): The characters in this slice.
- `count` (number): How many characters this response carries.
- `total` (number): How many characters matched before Limit/Offset.

**Example output**

```json
{
  "characters": [
    {
      "actor": "Daniel Radcliffe",
      "alive": true,
      "alternate_actors": [],
      "alternate_names": [
        "The Boy Who Lived",
        "The Chosen One",
        "Undesirable No. 1",
        "Potty"
      ],
      "ancestry": "half-blood",
      "dateOfBirth": "31-07-1980",
      "eyeColour": "green",
      "gender": "male",
      "hairColour": "black",
      "hogwartsStaff": false,
      "hogwartsStudent": true,
      "house": "Gryffindor",
      "id": "9e3f7ce4-b9a7-4244-b709-dae5c1f1d4a8",
      "image": "https://ik.imagekit.io/hpapi/harry.jpg",
      "name": "Harry Potter",
      "patronus": "stag",
      "species": "human",
      "wand": {
        "core": "phoenix tail feather",
        "length": 11,
        "wood": "holly"
      },
      "wizard": true,
      "yearOfBirth": 1980
    }
  ],
  "count": 1,
  "total": 437
}
```

### List characters by house

List the characters sorted into one Hogwarts house: Gryffindor, Hufflepuff, Ravenclaw, or Slytherin. Characters the books never sorted (muggles, creatures, other schools' students) belong to no house and appear in none of the four.

**Inputs**

- House (`house`, text, required): Which Hogwarts house to list. One of: `gryffindor`, `hufflepuff`, `ravenclaw`, `slytherin`. Default: `gryffindor`.
- Limit (`limit`, number): How many records to return at most (defaults to all of them). The API sends the whole collection in one response, so this trims it afterwards. At least 1.
- Offset (`offset`, number): How many records to skip before returning any (defaults to none). Pair it with Limit to walk a large collection a chunk at a time. At least 0.

**Outputs**

- `characters` (list): The house's characters in this slice.
- `count` (number): How many characters this response carries.
- `house` (text): The house that was listed, canonically spelled.
- `total` (number): How many characters matched before Limit/Offset.

**Example output**

```json
{
  "characters": [
    {
      "actor": "Daniel Radcliffe",
      "alive": true,
      "alternate_actors": [],
      "alternate_names": [
        "The Boy Who Lived",
        "The Chosen One",
        "Undesirable No. 1",
        "Potty"
      ],
      "ancestry": "half-blood",
      "dateOfBirth": "31-07-1980",
      "eyeColour": "green",
      "gender": "male",
      "hairColour": "black",
      "hogwartsStaff": false,
      "hogwartsStudent": true,
      "house": "Gryffindor",
      "id": "9e3f7ce4-b9a7-4244-b709-dae5c1f1d4a8",
      "image": "https://ik.imagekit.io/hpapi/harry.jpg",
      "name": "Harry Potter",
      "patronus": "stag",
      "species": "human",
      "wand": {
        "core": "phoenix tail feather",
        "length": 11,
        "wood": "holly"
      },
      "wizard": true,
      "yearOfBirth": 1980
    }
  ],
  "count": 1,
  "house": "Gryffindor",
  "total": 47
}
```

### List Hogwarts staff

List every Hogwarts staff member in the API: professors, the headmaster, the groundskeeper, and the caretaker.

**Inputs**

- Limit (`limit`, number): How many records to return at most (defaults to all of them). The API sends the whole collection in one response, so this trims it afterwards. At least 1.
- Offset (`offset`, number): How many records to skip before returning any (defaults to none). Pair it with Limit to walk a large collection a chunk at a time. At least 0.

**Outputs**

- `characters` (list): The staff members in this slice.
- `count` (number): How many characters this response carries.
- `total` (number): How many characters matched before Limit/Offset.

**Example output**

```json
{
  "characters": [
    {
      "actor": "Dame Maggie Smith",
      "alive": true,
      "alternate_actors": [],
      "alternate_names": [],
      "ancestry": "half-blood",
      "dateOfBirth": "04-10-1925",
      "eyeColour": "",
      "gender": "female",
      "hairColour": "black",
      "hogwartsStaff": true,
      "hogwartsStudent": false,
      "house": "Gryffindor",
      "id": "ca3827f0-375a-4891-aaa5-f5e8a5bad225",
      "image": "https://ik.imagekit.io/hpapi/mcgonagall.jpg",
      "name": "Minerva McGonagall",
      "patronus": "tabby cat",
      "species": "human",
      "wand": {
        "core": "dragon heartstring",
        "length": 9.5,
        "wood": "fir"
      },
      "wizard": true,
      "yearOfBirth": 1925
    }
  ],
  "count": 1,
  "total": 25
}
```

### List Hogwarts students

List every Hogwarts student in the API. Same character records as the full catalog, narrowed to those flagged as students.

**Inputs**

- Limit (`limit`, number): How many records to return at most (defaults to all of them). The API sends the whole collection in one response, so this trims it afterwards. At least 1.
- Offset (`offset`, number): How many records to skip before returning any (defaults to none). Pair it with Limit to walk a large collection a chunk at a time. At least 0.

**Outputs**

- `characters` (list): The students in this slice.
- `count` (number): How many characters this response carries.
- `total` (number): How many characters matched before Limit/Offset.

**Example output**

```json
{
  "characters": [
    {
      "actor": "Emma Watson",
      "alive": true,
      "alternate_actors": [],
      "alternate_names": [
        "Hermy",
        "Know-it-all",
        "Miss Grant",
        "Herm-own-ninny"
      ],
      "ancestry": "muggleborn",
      "dateOfBirth": "19-09-1979",
      "eyeColour": "brown",
      "gender": "female",
      "hairColour": "brown",
      "hogwartsStaff": false,
      "hogwartsStudent": true,
      "house": "Gryffindor",
      "id": "4c7e6819-a91a-45b2-a454-f931e4a7cce3",
      "image": "https://ik.imagekit.io/hpapi/hermione.jpeg",
      "name": "Hermione Granger",
      "patronus": "otter",
      "species": "human",
      "wand": {
        "core": "dragon heartstring",
        "length": 10.75,
        "wood": "vine"
      },
      "wizard": true,
      "yearOfBirth": 1979
    }
  ],
  "count": 1,
  "total": 103
}
```

### List spells

List every spell in the API, each with its incantation and a one-line description of what it does.

**Inputs**

- Limit (`limit`, number): How many records to return at most (defaults to all of them). The API sends the whole collection in one response, so this trims it afterwards. At least 1.
- Offset (`offset`, number): How many records to skip before returning any (defaults to none). Pair it with Limit to walk a large collection a chunk at a time. At least 0.

**Outputs**

- `count` (number): How many spells this response carries.
- `spells` (list): The spells in this slice.
- `total` (number): How many spells matched before Limit.

**Example output**

```json
{
  "count": 1,
  "spells": [
    {
      "description": "Illuminates the caster's wand",
      "id": "3b7a10ce-3339-4a36-9493-292c8775e47b",
      "name": "Lumos"
    }
  ],
  "total": 77
}
```

### Search characters

Find characters whose name or alternate names contain the search text, matched case-insensitively. The API has no search endpoint, so the whole catalog is fetched and filtered for you. This is how a workflow turns a name into the id the 'Get a character' action needs.

**Inputs**

- Search text (`query`, text, required): Text to look for in a character's name or alternate names, for example 'weasley' or 'the chosen one'.
- Limit (`limit`, number): How many matches to return at most (defaults to all of them). At least 1.

**Outputs**

- `characters` (list): The matching characters.
- `count` (number): How many characters this response carries.
- `total` (number): How many characters matched before Limit/Offset.

**Example output**

```json
{
  "characters": [
    {
      "actor": "Daniel Radcliffe",
      "alive": true,
      "alternate_actors": [],
      "alternate_names": [
        "The Boy Who Lived",
        "The Chosen One",
        "Undesirable No. 1",
        "Potty"
      ],
      "ancestry": "half-blood",
      "dateOfBirth": "31-07-1980",
      "eyeColour": "green",
      "gender": "male",
      "hairColour": "black",
      "hogwartsStaff": false,
      "hogwartsStudent": true,
      "house": "Gryffindor",
      "id": "9e3f7ce4-b9a7-4244-b709-dae5c1f1d4a8",
      "image": "https://ik.imagekit.io/hpapi/harry.jpg",
      "name": "Harry Potter",
      "patronus": "stag",
      "species": "human",
      "wand": {
        "core": "phoenix tail feather",
        "length": 11,
        "wood": "holly"
      },
      "wizard": true,
      "yearOfBirth": 1980
    }
  ],
  "count": 1,
  "total": 1
}
```

### Search spells

Find spells whose incantation or description contains the search text, matched case-insensitively. Because the description is searched too, a workflow can look a spell up by what it does ('unlock') as easily as by its name ('Alohomora').

**Inputs**

- Search text (`query`, text, required): Text to look for in a spell's incantation or description, for example 'alohomora' or 'unlock'.
- Limit (`limit`, number): How many matches to return at most (defaults to all of them). At least 1.

**Outputs**

- `count` (number): How many spells this response carries.
- `spells` (list): The matching spells.
- `total` (number): How many spells matched before Limit.

**Example output**

```json
{
  "count": 1,
  "spells": [
    {
      "description": "Unlocks objects",
      "id": "c9d2f389-a419-4f7e-8d3d-254959638019",
      "name": "Alohomora"
    }
  ],
  "total": 1
}
```