openapi: 3.0.3
info:
  title: Marvel Comics Characters API
  summary: Public REST API providing access to Marvel's library of comics, characters, creators, events, series, and stories spanning over 70 years of Marvel history.
  description: The Marvel Comics API allows developers to access information about Marvel's extensive catalog of characters, comics, creators, events, series, and stories. All requests must be authenticated using a public key, timestamp, and MD5 hash of the timestamp + private key + public key, supplied as query parameters.
  version: '1.0'
  contact:
    name: Marvel Developer Portal
    url: https://developer.marvel.com/
  license:
    name: Marvel API Terms of Use
    url: https://developer.marvel.com/terms
servers:
- url: https://gateway.marvel.com/v1/public
  description: Marvel Comics public API gateway
security:
- apiKeyAuth: []
  timestampAuth: []
  hashAuth: []
tags:
- name: Characters
  description: Marvel character resources.
paths:
  /characters:
    get:
      tags:
      - Characters
      summary: List characters
      description: Fetches lists of comic characters with optional filters.
      operationId: listCharacters
      parameters:
      - $ref: '#/components/parameters/name'
      - $ref: '#/components/parameters/nameStartsWith'
      - $ref: '#/components/parameters/modifiedSince'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Successful character data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CharacterDataWrapper'
  /characters/{characterId}:
    get:
      tags:
      - Characters
      summary: Get character by ID
      description: Fetches a single character by ID.
      operationId: getCharacter
      parameters:
      - $ref: '#/components/parameters/characterId'
      responses:
        '200':
          description: Successful character data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CharacterDataWrapper'
  /characters/{characterId}/comics:
    get:
      tags:
      - Characters
      summary: List comics for a character
      operationId: listCharacterComics
      parameters:
      - $ref: '#/components/parameters/characterId'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Successful comic data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComicDataWrapper'
components:
  schemas:
    CharacterDataWrapper:
      type: object
      properties:
        code:
          type: integer
        status:
          type: string
        copyright:
          type: string
        attributionText:
          type: string
        data:
          allOf:
          - $ref: '#/components/schemas/DataContainer'
          - type: object
            properties:
              results:
                type: array
                items:
                  type: object
    DataContainer:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        count:
          type: integer
    ComicDataWrapper:
      type: object
      properties:
        code:
          type: integer
        status:
          type: string
        data:
          allOf:
          - $ref: '#/components/schemas/DataContainer'
          - type: object
            properties:
              results:
                type: array
                items:
                  type: object
  parameters:
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 20
        maximum: 100
    nameStartsWith:
      name: nameStartsWith
      in: query
      schema:
        type: string
    modifiedSince:
      name: modifiedSince
      in: query
      schema:
        type: string
        format: date-time
    characterId:
      name: characterId
      in: path
      required: true
      schema:
        type: integer
    offset:
      name: offset
      in: query
      schema:
        type: integer
        default: 0
    name:
      name: name
      in: query
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: apikey
      description: Public API key issued from the Marvel Developer Portal.
    timestampAuth:
      type: apiKey
      in: query
      name: ts
      description: Timestamp (or other long string) used in the hash computation.
    hashAuth:
      type: apiKey
      in: query
      name: hash
      description: MD5 hash of ts + private key + public key.