openapi: 3.0.3
info:
  title: Superhero Characters Search 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: Search
  description: Search for characters by name.
paths:
  /{access-token}/search/{name}:
    get:
      operationId: searchCharacterByName
      summary: Search characters by name
      description: Searches for characters whose name matches or contains the provided name string. Returns an array of matching character records.
      tags:
      - Search
      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: name
        in: path
        required: true
        description: Character name or partial name to search for.
        schema:
          type: string
          example: batman
      responses:
        '200':
          description: Search results returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    enum:
                    - success
                    - error
                  results-for:
                    type: string
                    description: The name that was searched.
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Character'
        '400':
          description: No results or invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    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'
    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'
    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.
    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
    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