# Superhero API
> Over 560 comic and movie superheroes and villains as an API — Marvel, DC and beyond. Look up any character by id or name (e.g. Batman → DC Comics, alignment good, intelligence 81 / strength 40 / speed 29 / combat 90) or search and filter the whole roster by publisher and alignment. Each character carries the full profile: six powerstats (intelligence, strength, speed, durability, power, combat), biography (full name, alter-egos, place of birth, first appearance, publisher, alignment), appearance (gender, race, height, weight, eye and hair colour), occupation and base of operations, group affiliations and relatives, and character images. Backed by the open SuperHero Database. Ideal for comic and movie apps, trivia and quiz games, character-comparison tools, Discord bots and fan sites.

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

## Pricing
- **Free** (Free) — 8,000 calls/Mo, 2 req/s
- **Starter** ($3/Mo) — 120,000 calls/Mo, 8 req/s
- **Pro** ($11/Mo) — 600,000 calls/Mo, 20 req/s
- **Mega** ($33/Mo) — 2,600,000 calls/Mo, 50 req/s

## Endpoints

### Heroes

#### `GET /v1/hero` — A superhero by id or name

**Parameters:**
- `id` (query, optional, string) — Character id, e.g. 70 (Batman) Example: `70`
- `q` (query, optional, string) — Character name to resolve, e.g. Batman

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

**Response:**
```json
{
    "data": {
        "hero": {
            "id": 70,
            "name": "Batman",
            "slug": "70-batman",
            "work": {
                "base": "Batcave, Stately Wayne Manor, Gotham City; Hall of Justice, Justice League Watchtower",
                "occupation": "Businessman"
            },
            "images": {
                "lg": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/lg/70-batman.jpg",
                "md": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/md/70-batman.jpg",
                "sm": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/sm/70-batman.jpg",
                "xs": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/xs/70-batman.jpg"
            },
            "biography": {
                "aliases": [
                    "Insider",
                    "Matches Malone"
                ],
                "fullName": "Bruce Wayne",
                "alignment": "good",
                "alterEgos": "No alter egos found.",
                "publisher": "DC Comics",
                "placeOfBirth": "Crest Hill, Bristol Township; Gotham County",
                "firstAppearance": "Detective Comics #27"
            },
            "appearance": {
                "race": "Human",
                "gender": "Male",
                "height": [
                    "6'2",
                    "188 cm"
                ],
                "weight": [
                    "
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/list` — List / filter all heroes (paginated)

**Parameters:**
- `publisher` (query, optional, string) — Filter by publisher, e.g. DC Comics
- `alignment` (query, optional, string) — good | bad | neutral
- `page` (query, optional, string) — Page number (default 1) Example: `1`
- `limit` (query, optional, string) — Page size (1-100, default 30) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/superhero-api/v1/list?page=1&limit=30"
```

**Response:**
```json
{
    "data": {
        "page": 1,
        "count": 30,
        "total": 563,
        "results": [
            {
                "id": 1,
                "name": "A-Bomb",
                "slug": "1-a-bomb",
                "image": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/sm/1-a-bomb.jpg",
                "alignment": "good",
                "publisher": "Marvel Comics"
            },
            {
                "id": 2,
                "name": "Abe Sapien",
                "slug": "2-abe-sapien",
                "image": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/sm/2-abe-sapien.jpg",
                "alignment": "good",
                "publisher": "Dark Horse Comics"
            },
            {
                "id": 3,
                "name": "Abin Sur",
                "slug": "3-abin-sur",
                "image": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/sm/3-abin-sur.jpg",
                "alignment": "good",
                "publisher": "DC Comics"
            },
            {
                "id": 4,
                "name": "Abomination",
                "slug": "4-abomination",
                "image": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/sm/4-abomination.jpg",
                "alignment": "bad",
                "publisher": "Marvel Comics"
            },
            {
                "id": 5,
                "name": "Abraxas",
                "slug": "5-abra
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search heroes by name (+ filters)

**Parameters:**
- `q` (query, required, string) — Name to search, e.g. spider Example: `spider`
- `publisher` (query, optional, string) — Filter by publisher, e.g. Marvel Comics
- `alignment` (query, optional, string) — Filter by alignment: good | bad | neutral
- `limit` (query, optional, string) — Max results (1-100, default 20) Example: `20`

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

**Response:**
```json
{
    "data": {
        "count": 7,
        "query": "spider",
        "total": 7,
        "results": [
            {
                "id": 577,
                "name": "Scarlet Spider",
                "slug": "577-scarlet-spider",
                "image": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/sm/577-scarlet-spider.jpg",
                "alignment": "good",
                "publisher": "Spider-Carnage"
            },
            {
                "id": 578,
                "name": "Scarlet Spider II",
                "slug": "578-scarlet-spider-ii",
                "image": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/sm/578-scarlet-spider-ii.jpg",
                "alignment": "good",
                "publisher": "Marvel Comics"
            },
            {
                "id": 618,
                "name": "Spider-Girl",
                "slug": "618-spider-girl",
                "image": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/sm/618-spider-girl.jpg",
                "alignment": "good",
                "publisher": "Marvel Comics"
            },
            {
                "id": 619,
                "name": "Spider-Gwen",
                "slug": "619-spider-gwen",
                "image": "https://cdn.jsdelivr.net/gh/akabab/superhero-api@0.3.0/api/images/sm/619-spider-gwen.jpg",
                "alignment": "good",
                "publisher": "Marvel Comics"
            },
            {
      
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Counts, publishers & usage notes

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

**Response:**
```json
{
    "data": {
        "note": "Comic & movie superheroes. /v1/hero = one hero by id or name (e.g. id=70 or q=Batman) with powerstats, biography, appearance, work, connections and images; /v1/search = search by name with optional publisher/alignment filters; /v1/list = list/filter all heroes (publisher=, alignment=good|bad|neutral) with paging. Data is a fixed snapshot of the open SuperHero DB.",
        "source": "SuperHero Database (akabab/superhero-api) — bundled static snapshot",
        "endpoints": [
            "/v1/hero",
            "/v1/search",
            "/v1/list",
            "/v1/meta"
        ],
        "alignments": [
            "good",
            "bad",
            "neutral"
        ],
        "publishers": [
            "ABC Studios",
            "Angel",
            "Angel Salvadore",
            "Ant-Man",
            "Anti-Venom",
            "Anti-Vision",
            "Archangel",
            "Aztar",
            "Batgirl",
            "Batgirl III",
            "Batgirl V",
            "Batman II",
            "Binary",
            "Black Racer",
            "Boom-Boom",
            "DC Comics",
            "Dark Horse Comics",
            "Deadpool",
            "Evil Deadpool",
            "Flash IV",
            "Gemini V",
            "George Lucas",
            "Giant-Man",
            "Goliath",
            "IDW Publishing",
            "Icon Comics",
            "Image Comics",
            "Impulse",
            "Iron Lad",
            "J.
…(truncated, see openapi.json for full schema)
```


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