openapi: 3.0.3
info:
  title: Marvel Comics 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
tags:
  - name: Characters
    description: Marvel character resources.
  - name: Comics
    description: Marvel comic resources.
  - name: Creators
    description: Marvel creator resources.
  - name: Events
    description: Marvel event (crossover storyline) resources.
  - name: Series
    description: Marvel series resources.
  - name: Stories
    description: Marvel story resources.
security:
  - apiKeyAuth: []
    timestampAuth: []
    hashAuth: []
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
        - Comics
      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'
  /comics:
    get:
      tags:
        - Comics
      summary: List comics
      operationId: listComics
      parameters:
        - $ref: '#/components/parameters/title'
        - $ref: '#/components/parameters/titleStartsWith'
        - $ref: '#/components/parameters/modifiedSince'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Successful comic data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComicDataWrapper'
  /comics/{comicId}:
    get:
      tags:
        - Comics
      summary: Get comic by ID
      operationId: getComic
      parameters:
        - $ref: '#/components/parameters/comicId'
      responses:
        '200':
          description: Successful comic data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComicDataWrapper'
  /creators:
    get:
      tags:
        - Creators
      summary: List creators
      operationId: listCreators
      parameters:
        - $ref: '#/components/parameters/firstName'
        - $ref: '#/components/parameters/lastName'
        - $ref: '#/components/parameters/modifiedSince'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Successful creator data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorDataWrapper'
  /creators/{creatorId}:
    get:
      tags:
        - Creators
      summary: Get creator by ID
      operationId: getCreator
      parameters:
        - $ref: '#/components/parameters/creatorId'
      responses:
        '200':
          description: Successful creator data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorDataWrapper'
  /events:
    get:
      tags:
        - Events
      summary: List events
      operationId: listEvents
      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 event data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventDataWrapper'
  /events/{eventId}:
    get:
      tags:
        - Events
      summary: Get event by ID
      operationId: getEvent
      parameters:
        - $ref: '#/components/parameters/eventId'
      responses:
        '200':
          description: Successful event data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventDataWrapper'
  /series:
    get:
      tags:
        - Series
      summary: List series
      operationId: listSeries
      parameters:
        - $ref: '#/components/parameters/title'
        - $ref: '#/components/parameters/titleStartsWith'
        - $ref: '#/components/parameters/modifiedSince'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Successful series data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesDataWrapper'
  /series/{seriesId}:
    get:
      tags:
        - Series
      summary: Get series by ID
      operationId: getSeries
      parameters:
        - $ref: '#/components/parameters/seriesId'
      responses:
        '200':
          description: Successful series data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesDataWrapper'
  /stories:
    get:
      tags:
        - Stories
      summary: List stories
      operationId: listStories
      parameters:
        - $ref: '#/components/parameters/modifiedSince'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Successful story data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoryDataWrapper'
  /stories/{storyId}:
    get:
      tags:
        - Stories
      summary: Get story by ID
      operationId: getStory
      parameters:
        - $ref: '#/components/parameters/storyId'
      responses:
        '200':
          description: Successful story data wrapper.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoryDataWrapper'
components:
  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.
  parameters:
    characterId:
      name: characterId
      in: path
      required: true
      schema:
        type: integer
    comicId:
      name: comicId
      in: path
      required: true
      schema:
        type: integer
    creatorId:
      name: creatorId
      in: path
      required: true
      schema:
        type: integer
    eventId:
      name: eventId
      in: path
      required: true
      schema:
        type: integer
    seriesId:
      name: seriesId
      in: path
      required: true
      schema:
        type: integer
    storyId:
      name: storyId
      in: path
      required: true
      schema:
        type: integer
    name:
      name: name
      in: query
      schema:
        type: string
    nameStartsWith:
      name: nameStartsWith
      in: query
      schema:
        type: string
    title:
      name: title
      in: query
      schema:
        type: string
    titleStartsWith:
      name: titleStartsWith
      in: query
      schema:
        type: string
    firstName:
      name: firstName
      in: query
      schema:
        type: string
    lastName:
      name: lastName
      in: query
      schema:
        type: string
    modifiedSince:
      name: modifiedSince
      in: query
      schema:
        type: string
        format: date-time
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 20
        maximum: 100
    offset:
      name: offset
      in: query
      schema:
        type: integer
        default: 0
  schemas:
    DataContainer:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        count:
          type: integer
    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
    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
    CreatorDataWrapper:
      type: object
      properties:
        code:
          type: integer
        status:
          type: string
        data:
          allOf:
            - $ref: '#/components/schemas/DataContainer'
            - type: object
              properties:
                results:
                  type: array
                  items:
                    type: object
    EventDataWrapper:
      type: object
      properties:
        code:
          type: integer
        status:
          type: string
        data:
          allOf:
            - $ref: '#/components/schemas/DataContainer'
            - type: object
              properties:
                results:
                  type: array
                  items:
                    type: object
    SeriesDataWrapper:
      type: object
      properties:
        code:
          type: integer
        status:
          type: string
        data:
          allOf:
            - $ref: '#/components/schemas/DataContainer'
            - type: object
              properties:
                results:
                  type: array
                  items:
                    type: object
    StoryDataWrapper:
      type: object
      properties:
        code:
          type: integer
        status:
          type: string
        data:
          allOf:
            - $ref: '#/components/schemas/DataContainer'
            - type: object
              properties:
                results:
                  type: array
                  items:
                    type: object