Superhero API Characters API

openapi: 3.0.3
info:
  title: Superhero Characters API
  description: The Superhero API is a quantified and programmatically accessible data source of superheroes and villains from across comic book universes. It provides comprehensive character data for 731 heroes and villains including power stats, biography, appearance, work, connections, and image data from Marvel, DC, and other publishers. Developers authenticate via an API access token obtained through GitHub login and query characters by ID or name.
  version: 1.0.0
  contact:
    url: https://www.superheroapi.com/
  license:
    name: See superheroapi.com for terms
    url: https://www.superheroapi.com/
servers:
- url: https://superheroapi.com/api.php
  description: Superhero API production server
tags:
- name: Characters
  description: Retrieve full or partial character data by numeric ID.
paths:
  /{access-token}/{id}:
    get:
      operationId: getCharacterById
      summary: Get character by ID
      description: Returns the complete character record for the superhero or villain identified by the numeric ID, including all sub-sections (powerstats, biography, appearance, work, connections, image).
      tags:
      - Characters
      parameters:
      - name: access-token
        in: path
        required: true
        description: API access token obtained by logging in with GitHub at superheroapi.com.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Numeric character ID (1–731).
        schema:
          type: integer
          minimum: 1
          maximum: 731
          example: 70
      responses:
        '200':
          description: Character data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Character'
              example:
                response: success
                id: '70'
                name: Batman
                powerstats:
                  intelligence: '100'
                  strength: '26'
                  speed: '27'
                  durability: '50'
                  power: '47'
                  combat: '100'
                biography:
                  full-name: Bruce Wayne
                  alter-egos: No alter egos found.
                  aliases:
                  - Dark Knight
                  - Caped Crusader
                  place-of-birth: Crest Hill, Bristol Township, NJ
                  first-appearance: Detective Comics
                  publisher: DC Comics
                  alignment: good
                appearance:
                  gender: Male
                  race: Human
                  height:
                  - 6'2"
                  - 188 cm
                  weight:
                  - 210 lb
                  - 95 kg
                  eye-color: blue
                  hair-color: black
                work:
                  occupation: Businessman
                  base: Batcave, Stately Wayne Manor, Gotham City, New Jersey
                connections:
                  group-affiliation: Batman Family, Batman Incorporated, Justice League, Outsiders
                  relatives: Thomas Wayne (father, deceased), Martha Wayne (mother, deceased)
                image:
                  url: https://www.superheroapi.com/images/api/70/image.jpg
        '400':
          description: Invalid request or missing access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{access-token}/{id}/powerstats:
    get:
      operationId: getCharacterPowerstats
      summary: Get character power stats
      description: Returns only the powerstats sub-section for the specified character.
      tags:
      - Characters
      parameters:
      - name: access-token
        in: path
        required: true
        description: API access token obtained by logging in with GitHub at superheroapi.com.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Numeric character ID (1–731).
        schema:
          type: integer
          minimum: 1
          maximum: 731
          example: 70
      responses:
        '200':
          description: Powerstats data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PowerstatsResponse'
  /{access-token}/{id}/biography:
    get:
      operationId: getCharacterBiography
      summary: Get character biography
      description: Returns only the biography sub-section for the specified character.
      tags:
      - Characters
      parameters:
      - name: access-token
        in: path
        required: true
        description: API access token obtained by logging in with GitHub at superheroapi.com.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Numeric character ID (1–731).
        schema:
          type: integer
          minimum: 1
          maximum: 731
          example: 70
      responses:
        '200':
          description: Biography data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BiographyResponse'
  /{access-token}/{id}/appearance:
    get:
      operationId: getCharacterAppearance
      summary: Get character appearance
      description: Returns only the appearance sub-section for the specified character.
      tags:
      - Characters
      parameters:
      - name: access-token
        in: path
        required: true
        description: API access token obtained by logging in with GitHub at superheroapi.com.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Numeric character ID (1–731).
        schema:
          type: integer
          minimum: 1
          maximum: 731
          example: 70
      responses:
        '200':
          description: Appearance data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppearanceResponse'
  /{access-token}/{id}/work:
    get:
      operationId: getCharacterWork
      summary: Get character work
      description: Returns only the work sub-section for the specified character.
      tags:
      - Characters
      parameters:
      - name: access-token
        in: path
        required: true
        description: API access token obtained by logging in with GitHub at superheroapi.com.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Numeric character ID (1–731).
        schema:
          type: integer
          minimum: 1
          maximum: 731
          example: 70
      responses:
        '200':
          description: Work data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkResponse'
  /{access-token}/{id}/connections:
    get:
      operationId: getCharacterConnections
      summary: Get character connections
      description: Returns only the connections sub-section for the specified character.
      tags:
      - Characters
      parameters:
      - name: access-token
        in: path
        required: true
        description: API access token obtained by logging in with GitHub at superheroapi.com.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Numeric character ID (1–731).
        schema:
          type: integer
          minimum: 1
          maximum: 731
          example: 70
      responses:
        '200':
          description: Connections data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsResponse'
  /{access-token}/{id}/image:
    get:
      operationId: getCharacterImage
      summary: Get character image
      description: Returns only the image sub-section (portrait URL) for the specified character.
      tags:
      - Characters
      parameters:
      - name: access-token
        in: path
        required: true
        description: API access token obtained by logging in with GitHub at superheroapi.com.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Numeric character ID (1–731).
        schema:
          type: integer
          minimum: 1
          maximum: 731
          example: 70
      responses:
        '200':
          description: Image data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
components:
  schemas:
    Appearance:
      type: object
      description: Physical appearance attributes of the character.
      properties:
        gender:
          type: string
          description: Character's gender.
          example: Male
        race:
          type: string
          description: Character's race or species.
          example: Human
        height:
          type: array
          items:
            type: string
          description: Height expressed in imperial and metric units.
          example:
          - 6'2"
          - 188 cm
        weight:
          type: array
          items:
            type: string
          description: Weight expressed in imperial and metric units.
          example:
          - 210 lb
          - 95 kg
        eye-color:
          type: string
          description: Character's eye color.
          example: blue
        hair-color:
          type: string
          description: Character's hair color.
          example: black
    PowerstatsResponse:
      type: object
      properties:
        response:
          type: string
          enum:
          - success
          - error
        id:
          type: string
        name:
          type: string
        powerstats:
          $ref: '#/components/schemas/Powerstats'
    Connections:
      type: object
      description: Team affiliations and family/personal relationships.
      properties:
        group-affiliation:
          type: string
          description: Teams or groups the character is affiliated with.
          example: Batman Family, Batman Incorporated, Justice League, Outsiders
        relatives:
          type: string
          description: Known relatives or close personal connections.
          example: Thomas Wayne (father, deceased), Martha Wayne (mother, deceased)
    Character:
      type: object
      description: Complete character record including all sub-sections.
      properties:
        response:
          type: string
          enum:
          - success
          - error
          description: Response status indicator.
        id:
          type: string
          description: Numeric character ID as a string.
          example: '70'
        name:
          type: string
          description: Character's superhero or villain name.
          example: Batman
        powerstats:
          $ref: '#/components/schemas/Powerstats'
        biography:
          $ref: '#/components/schemas/Biography'
        appearance:
          $ref: '#/components/schemas/Appearance'
        work:
          $ref: '#/components/schemas/Work'
        connections:
          $ref: '#/components/schemas/Connections'
        image:
          $ref: '#/components/schemas/Image'
    AppearanceResponse:
      type: object
      properties:
        response:
          type: string
          enum:
          - success
          - error
        id:
          type: string
        name:
          type: string
        appearance:
          $ref: '#/components/schemas/Appearance'
    Biography:
      type: object
      description: Biographical details about the character.
      properties:
        full-name:
          type: string
          description: The character's real or full name.
          example: Bruce Wayne
        alter-egos:
          type: string
          description: Alternate ego names, or "No alter egos found." if none.
          example: No alter egos found.
        aliases:
          type: array
          items:
            type: string
          description: List of known aliases.
          example:
          - Dark Knight
          - Caped Crusader
        place-of-birth:
          type: string
          description: Location where the character was born.
          example: Crest Hill, Bristol Township, NJ
        first-appearance:
          type: string
          description: Comic issue of the character's first appearance.
          example: Detective Comics
        publisher:
          type: string
          description: The comic publisher (e.g., DC Comics, Marvel Comics).
          example: DC Comics
        alignment:
          type: string
          description: Moral alignment of the character.
          enum:
          - good
          - bad
          - neutral
          example: good
    Image:
      type: object
      description: Portrait image URL for the character.
      properties:
        url:
          type: string
          format: uri
          description: Direct URL to the character's portrait image.
          example: https://www.superheroapi.com/images/api/70/image.jpg
    ErrorResponse:
      type: object
      properties:
        response:
          type: string
          enum:
          - error
          description: Error status indicator.
        error:
          type: string
          description: Human-readable error message.
    ImageResponse:
      type: object
      properties:
        response:
          type: string
          enum:
          - success
          - error
        id:
          type: string
        name:
          type: string
        image:
          $ref: '#/components/schemas/Image'
    BiographyResponse:
      type: object
      properties:
        response:
          type: string
          enum:
          - success
          - error
        id:
          type: string
        name:
          type: string
        biography:
          $ref: '#/components/schemas/Biography'
    Powerstats:
      type: object
      description: Numeric ratings (0–100) for the six core power attributes of a character.
      properties:
        intelligence:
          type: string
          description: Intelligence rating (0–100 or "null").
          example: '100'
        strength:
          type: string
          description: Strength rating (0–100 or "null").
          example: '26'
        speed:
          type: string
          description: Speed rating (0–100 or "null").
          example: '27'
        durability:
          type: string
          description: Durability rating (0–100 or "null").
          example: '50'
        power:
          type: string
          description: Power rating (0–100 or "null").
          example: '47'
        combat:
          type: string
          description: Combat rating (0–100 or "null").
          example: '100'
    WorkResponse:
      type: object
      properties:
        response:
          type: string
          enum:
          - success
          - error
        id:
          type: string
        name:
          type: string
        work:
          $ref: '#/components/schemas/Work'
    Work:
      type: object
      description: Occupation and home base of the character.
      properties:
        occupation:
          type: string
          description: Character's occupation or profession.
          example: Businessman
        base:
          type: string
          description: Character's primary operating base or home location.
          example: Batcave, Stately Wayne Manor, Gotham City, New Jersey
    ConnectionsResponse:
      type: object
      properties:
        response:
          type: string
          enum:
          - success
          - error
        id:
          type: string
        name:
          type: string
        connections:
          $ref: '#/components/schemas/Connections'