openapi: 3.0.3
info:
  title: Marvel Comics Characters Events 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: Events
  description: Marvel event (crossover storyline) resources.
paths:
  /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'
components:
  schemas:
    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
    DataContainer:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        count:
          type: integer
  parameters:
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 20
        maximum: 100
    nameStartsWith:
      name: nameStartsWith
      in: query
      schema:
        type: string
    eventId:
      name: eventId
      in: path
      required: true
      schema:
        type: integer
    modifiedSince:
      name: modifiedSince
      in: query
      schema:
        type: string
        format: date-time
    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.