openapi: 3.0.3
info:
  title: Breaking Bad API
  description: >-
    Community-built REST API exposing characters, quotes, episodes, and deaths
    from the Breaking Bad and Better Call Saul television universe. The original
    upstream provider (breakingbadapi.com) is no longer reachable as of 2026 —
    DNS resolution fails and the documentation site at
    https://breakingbadapi.com/documentation returns no response. This OpenAPI
    document is preserved as a historical record of the API's documented
    contract, drawn from the canonical source repository at
    github.com/timbiles/Breaking-Bad--API and from archived community
    documentation (drangovski.github.io, mridul.tech/breaking-bad-api).
  version: "1.0.0"
  contact:
    name: Tim Biles (original maintainer)
    url: https://github.com/timbiles/Breaking-Bad--API
  license:
    name: BSD-3-Clause
    url: https://github.com/timbiles/Breaking-Bad--API/blob/master/LICENSE.rst
  x-generated-from: documentation
  x-last-validated: "2026-05-29"
  x-status: deprecated
  x-deprecation-note: >-
    The hosted service at breakingbadapi.com is unreachable as of 2026-05-29
    (DNS does not resolve). Schema and operations are preserved here for
    historical reference and to support nostalgic/educational re-implementations.
servers:
  - url: https://www.breakingbadapi.com/api
    description: Original community-hosted endpoint (unreachable as of 2026)
tags:
  - name: Characters
    description: Characters from the Breaking Bad and Better Call Saul universe.
  - name: Quotes
    description: Memorable quotes attributed to characters.
  - name: Episodes
    description: Episodes from the Breaking Bad and Better Call Saul series.
  - name: Deaths
    description: On-screen deaths catalogued across the series.
paths:
  /characters:
    get:
      operationId: listCharacters
      summary: List Characters
      description: Returns a list of every character from the Breaking Bad and Better Call Saul universe.
      tags:
        - Characters
      parameters:
        - name: limit
          in: query
          description: Maximum number of characters to return.
          required: false
          schema:
            type: integer
            minimum: 1
            example: 10
        - name: offset
          in: query
          description: Number of characters to skip before starting to collect the result set.
          required: false
          schema:
            type: integer
            minimum: 0
            example: 0
        - name: name
          in: query
          description: Filter characters by full name. Use `+` for spaces (e.g. `Walter+White`).
          required: false
          schema:
            type: string
            example: Walter+White
        - name: category
          in: query
          description: Filter by series — `Breaking+Bad`, `Better+Call+Saul`, or both joined by `,`.
          required: false
          schema:
            type: string
            example: Breaking+Bad,Better+Call+Saul
      responses:
        "200":
          description: Array of character records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Character"
              examples:
                ListCharacters200Example:
                  summary: Default listCharacters 200 response
                  x-microcks-default: true
                  value:
                    - char_id: 1
                      name: Walter White
                      birthday: 09-07-1958
                      occupation:
                        - High School Chemistry Teacher
                        - Meth King Pin
                      img: https://images.amcnetworks.com/amc.com/wp-content/uploads/2015/04/cast_bb_700x1000_walter-white-lg.jpg
                      status: Presumed dead
                      nickname: Heisenberg
                      appearance:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                      portrayed: Bryan Cranston
                      category: Breaking Bad
                      better_call_saul_appearance: []
                    - char_id: 2
                      name: Jesse Pinkman
                      birthday: 09-24-1984
                      occupation:
                        - Methamphetamine Manufacturer
                        - Distributor
                      img: https://images.amcnetworks.com/amc.com/wp-content/uploads/2015/04/cast_bb_700x1000_jesse-pinkman-lg.jpg
                      status: Alive
                      nickname: Cap n' Cook
                      appearance:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                      portrayed: Aaron Paul
                      category: Breaking Bad
                      better_call_saul_appearance: []
        "429":
          $ref: "#/components/responses/RateLimited"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /characters/{id}:
    get:
      operationId: getCharacterById
      summary: Get Character By Id
      description: Returns a single character by numeric id.
      tags:
        - Characters
      parameters:
        - name: id
          in: path
          required: true
          description: Numeric character id.
          schema:
            type: integer
            example: 1
      responses:
        "200":
          description: Character record (array with a single element, as returned by the upstream service).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Character"
              examples:
                GetCharacterById200Example:
                  summary: Default getCharacterById 200 response
                  x-microcks-default: true
                  value:
                    - char_id: 1
                      name: Walter White
                      birthday: 09-07-1958
                      occupation:
                        - High School Chemistry Teacher
                        - Meth King Pin
                      img: https://images.amcnetworks.com/amc.com/wp-content/uploads/2015/04/cast_bb_700x1000_walter-white-lg.jpg
                      status: Presumed dead
                      nickname: Heisenberg
                      appearance:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                      portrayed: Bryan Cranston
                      category: Breaking Bad
                      better_call_saul_appearance: []
        "404":
          $ref: "#/components/responses/NotFound"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /character/random:
    get:
      operationId: getRandomCharacter
      summary: Get Random Character
      description: Returns one randomly selected character.
      tags:
        - Characters
      responses:
        "200":
          description: One character record, wrapped in an array.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Character"
              examples:
                GetRandomCharacter200Example:
                  summary: Default getRandomCharacter 200 response
                  x-microcks-default: true
                  value:
                    - char_id: 17
                      name: Saul Goodman
                      birthday: 11-12-1960
                      occupation:
                        - Lawyer
                      img: https://images.amcnetworks.com/amc.com/wp-content/uploads/2015/04/cast_bb_700x1000_saul-goodman-lg.jpg
                      status: Alive
                      nickname: Slippin' Jimmy
                      appearance:
                        - 2
                        - 3
                        - 4
                        - 5
                      portrayed: Bob Odenkirk
                      category: Breaking Bad, Better Call Saul
                      better_call_saul_appearance:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                        - 6
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /quotes:
    get:
      operationId: listQuotes
      summary: List Quotes
      description: Returns every catalogued quote across the series.
      tags:
        - Quotes
      responses:
        "200":
          description: Array of quote records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Quote"
              examples:
                ListQuotes200Example:
                  summary: Default listQuotes 200 response
                  x-microcks-default: true
                  value:
                    - quote_id: 1
                      quote: I am not in danger, Skyler. I am the danger.
                      author: Walter White
                      series: Breaking Bad
                    - quote_id: 2
                      quote: Yeah Mr. White! Yeah Science!
                      author: Jesse Pinkman
                      series: Breaking Bad
        "429":
          $ref: "#/components/responses/RateLimited"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /quotes/{id}:
    get:
      operationId: getQuoteById
      summary: Get Quote By Id
      description: Returns one quote by numeric id.
      tags:
        - Quotes
      parameters:
        - name: id
          in: path
          required: true
          description: Numeric quote id.
          schema:
            type: integer
            example: 1
      responses:
        "200":
          description: Quote record, wrapped in an array.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Quote"
              examples:
                GetQuoteById200Example:
                  summary: Default getQuoteById 200 response
                  x-microcks-default: true
                  value:
                    - quote_id: 1
                      quote: I am not in danger, Skyler. I am the danger.
                      author: Walter White
                      series: Breaking Bad
        "404":
          $ref: "#/components/responses/NotFound"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /quote/random:
    get:
      operationId: getRandomQuote
      summary: Get Random Quote
      description: Returns one randomly selected quote, optionally filtered by author.
      tags:
        - Quotes
      parameters:
        - name: author
          in: query
          description: Filter random selection by author. Use `+` for spaces (e.g. `Jesse+Pinkman`).
          required: false
          schema:
            type: string
            example: Jesse+Pinkman
      responses:
        "200":
          description: One quote record, wrapped in an array.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Quote"
              examples:
                GetRandomQuote200Example:
                  summary: Default getRandomQuote 200 response
                  x-microcks-default: true
                  value:
                    - quote_id: 5
                      quote: You either run from things, or you face them, Mr. White.
                      author: Jesse Pinkman
                      series: Breaking Bad
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /episodes:
    get:
      operationId: listEpisodes
      summary: List Episodes
      description: Returns every episode across Breaking Bad and Better Call Saul.
      tags:
        - Episodes
      parameters:
        - name: series
          in: query
          description: Filter episodes by series — `Breaking+Bad` or `Better+Call+Saul`.
          required: false
          schema:
            type: string
            example: Breaking+Bad
      responses:
        "200":
          description: Array of episode records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Episode"
              examples:
                ListEpisodes200Example:
                  summary: Default listEpisodes 200 response
                  x-microcks-default: true
                  value:
                    - episode_id: 1
                      title: Pilot
                      season: '1'
                      air_date: 01-20-2008
                      characters:
                        - Walter White
                        - Jesse Pinkman
                        - Skyler White
                        - Hank Schrader
                        - Marie Schrader
                        - Walter White Jr.
                      episode: '1'
                      series: Breaking Bad
                    - episode_id: 62
                      title: Felina
                      season: '5'
                      air_date: 09-29-2013
                      characters:
                        - Walter White
                        - Jesse Pinkman
                        - Skyler White
                        - Lydia Rodarte-Quayle
                        - Todd Alquist
                      episode: '16'
                      series: Breaking Bad
        "429":
          $ref: "#/components/responses/RateLimited"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /episodes/{id}:
    get:
      operationId: getEpisodeById
      summary: Get Episode By Id
      description: Returns one episode by numeric id.
      tags:
        - Episodes
      parameters:
        - name: id
          in: path
          required: true
          description: Numeric episode id.
          schema:
            type: integer
            example: 1
      responses:
        "200":
          description: Episode record, wrapped in an array.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Episode"
              examples:
                GetEpisodeById200Example:
                  summary: Default getEpisodeById 200 response
                  x-microcks-default: true
                  value:
                    - episode_id: 1
                      title: Pilot
                      season: '1'
                      air_date: 01-20-2008
                      characters:
                        - Walter White
                        - Jesse Pinkman
                        - Skyler White
                        - Hank Schrader
                      episode: '1'
                      series: Breaking Bad
        "404":
          $ref: "#/components/responses/NotFound"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /deaths:
    get:
      operationId: listDeaths
      summary: List Deaths
      description: Returns every catalogued on-screen death across the series.
      tags:
        - Deaths
      responses:
        "200":
          description: Array of death records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Death"
              examples:
                ListDeaths200Example:
                  summary: Default listDeaths 200 response
                  x-microcks-default: true
                  value:
                    - death_id: 1
                      death: Emilio Koyama
                      cause: Poison Gas
                      responsible: Walter White
                      last_words: No, please!
                      season: 1
                      episode: 1
                      number_of_deaths: 1
        "429":
          $ref: "#/components/responses/RateLimited"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /death-count:
    get:
      operationId: getDeathCount
      summary: Get Death Count
      description: Returns the total number of catalogued deaths, optionally filtered by the character responsible.
      tags:
        - Deaths
      parameters:
        - name: name
          in: query
          description: Filter the count by the character responsible for the deaths.
          required: false
          schema:
            type: string
            example: Gustavo+Fring
      responses:
        "200":
          description: Integer death count.
          content:
            application/json:
              schema:
                type: integer
                example: 270
              examples:
                GetDeathCount200Example:
                  summary: Default getDeathCount 200 response
                  x-microcks-default: true
                  value: 270
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /random-death:
    get:
      operationId: getRandomDeath
      summary: Get Random Death
      description: Returns one randomly selected on-screen death.
      tags:
        - Deaths
      responses:
        "200":
          description: One death record.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Death"
              examples:
                GetRandomDeath200Example:
                  summary: Default getRandomDeath 200 response
                  x-microcks-default: true
                  value:
                    death_id: 14
                    death: Tortuga
                    cause: Decapitation
                    responsible: The Cousins
                    last_words: Unknown
                    season: 2
                    episode: 7
                    number_of_deaths: 1
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Character:
      type: object
      description: A character from the Breaking Bad or Better Call Saul series.
      x-schema-source: documentation
      x-source-url: https://github.com/timbiles/Breaking-Bad--API
      properties:
        char_id:
          type: integer
          description: Unique numeric id for the character.
          example: 1
        name:
          type: string
          description: Character's full name.
          example: Walter White
        birthday:
          type: string
          description: Character's birthday in M-D-YYYY format.
          example: 09-07-1958
        occupation:
          type: array
          description: List of the character's known occupations.
          items:
            type: string
          example:
            - High School Chemistry Teacher
            - Meth King Pin
        img:
          type: string
          format: uri
          description: URL of the character's portrait image (JPG).
          example: https://images.amcnetworks.com/amc.com/wp-content/uploads/2015/04/cast_bb_700x1000_walter-white-lg.jpg
        status:
          type: string
          description: Whether the character is alive, deceased, or presumed dead.
          example: Presumed dead
        nickname:
          type: string
          description: A known nickname.
          example: Heisenberg
        appearance:
          type: array
          description: List of Breaking Bad seasons in which the character appeared.
          items:
            type: integer
          example: [1, 2, 3, 4, 5]
        portrayed:
          type: string
          description: Actor who portrayed the character.
          example: Bryan Cranston
        category:
          type: string
          description: Comma-separated list of series the character appears in.
          example: Breaking Bad, Better Call Saul
        better_call_saul_appearance:
          type: array
          description: List of Better Call Saul seasons in which the character appeared.
          items:
            type: integer
          example: []
    Quote:
      type: object
      description: A memorable quote attributed to a character.
      x-schema-source: documentation
      x-source-url: https://github.com/timbiles/Breaking-Bad--API
      properties:
        quote_id:
          type: integer
          description: Unique numeric id for the quote.
          example: 1
        quote:
          type: string
          description: The text of the quote.
          example: I am not in danger, Skyler. I am the danger.
        author:
          type: string
          description: The character credited with the quote.
          example: Walter White
        series:
          type: string
          description: The series the quote originated from.
          example: Breaking Bad
    Episode:
      type: object
      description: An episode of Breaking Bad or Better Call Saul.
      x-schema-source: documentation
      x-source-url: https://github.com/timbiles/Breaking-Bad--API
      properties:
        episode_id:
          type: integer
          description: Unique numeric id for the episode.
          example: 1
        title:
          type: string
          description: Episode title.
          example: Pilot
        season:
          type: string
          description: Season number as a string (zero-padded by upstream).
          example: "1"
        air_date:
          type: string
          description: Original air date in M-D-YYYY format.
          example: 01-20-2008
        characters:
          type: array
          description: Characters appearing in the episode.
          items:
            type: string
          example:
            - Walter White
            - Jesse Pinkman
        episode:
          type: string
          description: Episode number within the season (zero-padded by upstream).
          example: "1"
        series:
          type: string
          description: Series the episode belongs to — `Breaking Bad` or `Better Call Saul`.
          example: Breaking Bad
    Death:
      type: object
      description: A catalogued on-screen death from the series.
      x-schema-source: documentation
      x-source-url: https://github.com/timbiles/Breaking-Bad--API
      properties:
        death_id:
          type: integer
          description: Unique numeric id for the death record.
          example: 1
        death:
          type: string
          description: The name of the character who died.
          example: Emilio Koyama
        cause:
          type: string
          description: How the character died.
          example: Poison Gas
        responsible:
          type: string
          description: Character responsible for the death.
          example: Walter White
        last_words:
          type: string
          description: The character's documented last words.
          example: No, please!
        season:
          type: integer
          description: Season the death occurred in.
          example: 1
        episode:
          type: integer
          description: Episode the death occurred in.
          example: 1
        number_of_deaths:
          type: integer
          description: Number of deaths attributed to this single record.
          example: 1
    Error:
      type: object
      description: Generic error envelope.
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: Not Found
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            NotFoundExample:
              summary: Default 404 response
              x-microcks-default: true
              value:
                message: Not Found
    RateLimited:
      description: Rate limit exceeded. The original upstream enforced 10,000 requests per day per IP and returned 429 until the 24-hour window rolled over.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            RateLimitedExample:
              summary: Default 429 response
              x-microcks-default: true
              value:
                message: Rate limit exceeded. Try again in 24 hours.