openapi: 3.0.3
info:
  title: Marvel Comics Characters Stories 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: Stories
  description: Marvel story resources.
paths:
  /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:
  parameters:
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 20
        maximum: 100
    modifiedSince:
      name: modifiedSince
      in: query
      schema:
        type: string
        format: date-time
    offset:
      name: offset
      in: query
      schema:
        type: integer
        default: 0
    storyId:
      name: storyId
      in: path
      required: true
      schema:
        type: integer
  schemas:
    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
    DataContainer:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        count:
          type: integer
  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.