The Supernatural API - The Docs

This is a consumption-only API — only the HTTP GET method is available on resources. It is NOT an official API for Supernatural nor this is endorsed by CW or WB.
At this time, no authentication is required to access this API.

Using this API is free of charge, but if you wanted to support its development, feel free to buy the dev team a coffee!

SPOILER ALERT! This API features quotes from the original source as well as The Winchesters.

Base endpoint:

https://supernatural-quotes-api.cyclic.app

Query params available to all endpoints: 

?page=''&size=''

Quotes

GET all quotes

/quotes

Query params:

It's possible to use query params to perform a research.
Here are the available properties: 
?ep=''&season=''&char=''&title=''
?char=Dean Winchester,Jo Harvelle&title=No Exit&page=1

Response:

Types: 
            
type lineNum = string
interface Quote {
    id: string
    [key: `line_${lineNum}`]: { //each quote can have an x amount of "line_y" properties.
        character: {
            name: string
            id: string
        }
        quote: string
    }
}   

interface ApiResp {
  data: Quote[],
  next: string | null 
  prev: string | null
  count: number //the total amount of quotes in the db
  resultCount: number //the total amount of quotes found with the query provided. 
}
Example data:
            
{
  data: [
          {
            "line_0": {
                "character": {
                    "name": "Claire Novak",
                    "id": "5441xkkfwlhdv7d97"
                },
                "quote": "Hello? Uh, this is Agent Beatrice Quimby."
            },
            "line_1": {
                "character": {
                    "name": "Dean Winchester (with bad accent)",
                    "id": "5441xkkfwlhdv8gbq"
                },
                "quote": "Oh, thank God. There's a bear. It's the size of a freakin' tank! I think it wants my pic-a-nic basket!"
            },
            "line_2": {
                "character": {
                    "name": "Claire Novak",
                    "id": "5441xkkfwlhdv7d97"
                },
                "quote": "Mm-hmm. Hi, Dean."
            },
            "id": "5441xkj2glh9g39mp"
          },
          {...},
          {...},
          {...},
  ],
  next: "",
  prev: "",
  count: 400,
  resultCount: 23
  
}

GET a random quote 

/quotes/random
Example data:
            
{
  "line_0": {
    "character": {
      "name": "Castiel (to Dean)",
      "id": "5441xkkfwlhdv6rj8"
    },
    "quote": "If I plan to do anything else stupid, I'll let you know."
  },
  "id": "5441xkj2glh9g3ccf"
}

Characters

GET all characters 

/characters

Query params:

It's possible to use query params to perform a research.
Here are the available properties: 
?name=''&actor=''&episodes=''&occupation=''
To search by episode you can either enter the episode name or the episode number, with the following format: 
?episodes=7.06
?episodes=slash fiction
Searching by episode will bring up similar episode numbers. For example 
 ?episodes=5.04
will also give back characters that appeared in 15.04

Response:

Types:
            
interface Character {
  name: string 
  img: string 
  actor: string[]
  episodes: {title: string, id: string}[]
  occupation: string[]
  id: string
}

interface ApiResp {
  data: Character[],
  next: string | null 
  prev: string | null
  count: number //the total amount of chars in the db
  resultCount: number //the total amount of quotes found with the query provided. 
}

Example data:


{
  data: [
  {
    "name": "Aaron Bass",
    "img": "https://supernatural-api.onrender.com/images/350px-Aaron_Bass.png",
    "actor": [
        "Adam Rose"
    ],
    "episodes": [
        {
            "title": "8.13 Everybody Hates Hitler",
            "id": "5441xkfs0li0res0t"
        },
        {
            "title": "12.05 The One You've Been Waiting For",
            "id": "5441xkfs0li0rfcyr"
        }
    ],
    "occupation": [
        "Judah Initiative"
    ],
    "id": "5441xkkfwlhdv3rk5"
},
    {...},
    {...}
  ],
  next: "",
  prev: "",
  count: 1000
  resultCoult: 87
}

GET character by id 

/characters/:id
Example data:

{
    "name": "Abaddon",
    "img": "https://supernatural-api.onrender.com/images/350px-Abaddon001.png",
    "actor": [
        "Alaina Huffman",
        "Sharon Bell",
        "Anna Galvin",
        "Marilyn Norry"
    ],
    "episodes": [
        {
            "title": "8.12 As Time Goes By",
            "id": "5441xkfs0li0rersj"
        },
        {
            "title": "8.22 Clip Show",
            "id": "5441xkfs0li0reuof"
        },
        {
            "title": "8.23 Sacrifice",
            "id": "5441xkfs0li0reuxc"
        },
        {
            "title": "9.02 Devil May Care",
            "id": "5441xkfs0li0revf0"
        },
        {
            "title": "9.06 Heaven Can't Wait",
            "id": "5441xkfs0li0rewe8"
        },
        {
            "title": "9.10 Road Trip",
            "id": "5441xkfs0li0rexb5"
        },
        {
            "title": "9.11 First Born",
            "id": "5441xkfs0li0rexjx"
        },
        {
            "title": "9.17 Mother's Little Helper",
            "id": "5441xkfs0li0reyy3"
        },
        {
            "title": "9.21 King of the Damned",
            "id": "5441xkfs0li0rf02j"
        }
    ],
    "occupation": [
        "Demon",
        "Knight of Hell"
    ],
    "id": "5441xkkfwlhdv3t32"
},

Episodes

GET all episodes 

/episodes

Query params:

It's possible to use query params to perform a research.
Here are the available properties: 
?title=''&season=''&ep=''

Response:

Types: 
  
interface Episode {
  id: string 
  title: string 
  season: string 
  ep: string 
  chars: string[]
}

interface ApiResp {
  data: Episode[]
  next: string | null 
  prev: string | null
  count: number //the total amount of chars in the db
  resultCount: number //the total amount of quotes found with the query provided. 
}
Example data:
 
{
  "data": [
    {
      "id": "5441xkfs0li0rdo01",
      "title": "Pilot",
      "season": "1",
      "ep": "01",
      "chars": [
        "5441xkkfwlhdvkrvm",
        "5441xkkfwlhdv8fe8",
        "5441xkkfwlhdve21s",
        "5441xkkfwlhdvgs70",
        "5441xkkfwlhdvdqnl",
        "5441xkkfwlhdv5dyn",
        "5441xkkfwlhdv7o8g",
        "5441xkkfwlhdve6m6",
        "5441xkgxcli0qvvi6",
        "5441xkkfwlhdv4plp"
      ]
    },
    {
      "id": "5441xkfs0li0rdocr",
      "title": "Wendigo",
      "season": "1",
      "ep": "02",
      "chars": [
        "5441xkkfwlhdvkrvm",
        "5441xkkfwlhdv8fe8",
        "5441xkkfwlhdvc2z3",
        "5441xkkfwlhdv5pib",
        "5441xkgxcli0qvwei",
        "5441xkkfwlhdvkgsd",
        "5441xkkfwlhdvjo0j",
        "5441xkkfwlhdvlf2g"
      ]
    },
    { ... },
    { ... },
    { ... }
  ]
}

GET episode by id 

/episodes/:id
Types: 

interface EpisodeSingle {
  id: string 
  title: string 
  season: string 
  ep: string 
  chars: Character[]
}
Example data:
 
{
  "id": "5441xkfs0li0rdo01",
  "title": "Pilot",
  "season": "1",
  "ep": "01",
  "chars": [
    {
      "name": "Sam Winchester",
      "img": "https://supernatural-api.onrender.com/images/350px-SamWinchester.png",
      "actor": [
        "Jared Padalecki",
        "Alex Ferris",
        "Colin Ford",
        "Nathan Smith",
        "Hunter Dillon",
        "Dylan Kingwell",
        "Christian Michael Cooper"
      ],
      "episodes": [],
      "occupation": ["Hunter"],
      "id": "5441xkkfwlhdvkrvm",
      "location": "Heaven"
    },
    {
      "name": "Dean Winchester",
      "img": "https://supernatural-api.onrender.com/images/350px-DeanWinchester.png",
      "actor": [
        "Jensen Ackles",
        "Hunter Brochu",
        "Ridge Canipe",
        "Brock Kelly",
        "Chad Everett",
        "Nicolai Guistra",
        "Dylan Everett",
        "Anthony Bolognese",
        "Paxton Singleton"
    ],
    "episodes": [
      {
        "title": "14.01 Stranger in a Strange Land",
        "id": "5441xkfs0li0rfnjd"
      }
    ],
    "occupation": [ "Hunter" ],
    "id": "5441xkkfwlhdv8fe8",
    "location": "Heaven"
    },
    { ... }, 
    { ... }, 
    { ... }, 
    { ... }, 
    { ... }
  ]
}
The Supernatural API