openapi: 3.0.3
info:
  title: Market Data Indices Options API
  description: The Market Data API delivers real-time and historical U.S. stock, options, and index market data over a simple REST interface. All endpoints are served from https://api.marketdata.app/v1 and return JSON (or CSV) responses. Most endpoints require only a ticker symbol as a path parameter. Requests are authenticated with a Bearer token generated in the Market Data dashboard. Coverage spans stock candles and quotes (single and bulk), corporate earnings and news, full options chains with per-contract quotes, expirations, strikes and OCC symbol lookup, index candles and quotes, and market open/closed status. Note that Market Data may return HTTP 203 Non-Authoritative Information (instead of 200 OK) when a response is served from its caching tier; clients must treat 203 as success.
  version: '1.0'
  contact:
    name: Market Data
    url: https://www.marketdata.app
  termsOfService: https://www.marketdata.app/terms/
servers:
- url: https://api.marketdata.app/v1
  description: Market Data API v1
security:
- bearerAuth: []
tags:
- name: Options
  description: Options chains, per-contract quotes, expirations, strikes, and OCC symbol lookup.
paths:
  /options/expirations/{underlyingSymbol}/:
    get:
      operationId: getOptionExpirations
      tags:
      - Options
      summary: Option expirations
      description: Get a list of current or historical option expiration dates for an underlying symbol. With no optional parameters, returns all expiration dates in the option chain.
      parameters:
      - name: underlyingSymbol
        in: path
        required: true
        description: The underlying ticker symbol for the options chain.
        schema:
          type: string
      responses:
        '200':
          description: Expiration dates for the underlying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '203':
          description: Cached expiration dates (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /options/lookup/{userInput}/:
    get:
      operationId: getOptionLookup
      tags:
      - Options
      summary: Option symbol lookup
      description: Convert a human-readable string containing a stock symbol, strike, expiration date, and option side (put or call) into a valid OCC option symbol.
      parameters:
      - name: userInput
        in: path
        required: true
        description: Human-readable option description, e.g. "AAPL 7/28/23 $200 Call".
        schema:
          type: string
      responses:
        '200':
          description: The resolved OCC option symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '203':
          description: Cached lookup result (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /options/strikes/{underlyingSymbol}/:
    get:
      operationId: getOptionStrikes
      tags:
      - Options
      summary: Option strikes
      description: Get a list of current or historical option strike prices for an underlying symbol. With no optional parameters, returns the strikes for every expiration in the chain.
      parameters:
      - name: underlyingSymbol
        in: path
        required: true
        description: The underlying ticker symbol for the options chain.
        schema:
          type: string
      - name: expiration
        in: query
        required: false
        description: Limit strikes to a single expiration date.
        schema:
          type: string
      responses:
        '200':
          description: Strike prices for the underlying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '203':
          description: Cached strike prices (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /options/chain/{underlyingSymbol}/:
    get:
      operationId: getOptionChain
      tags:
      - Options
      summary: Option chain
      description: Get a current or historical end-of-day option chain for an underlying ticker symbol, with extensive optional filtering (expiration, strike range, side, moneyness, delta, and more). Each option symbol included in the response consumes credits, so large chains such as SPX can be expensive.
      parameters:
      - name: underlyingSymbol
        in: path
        required: true
        description: The underlying ticker symbol for the options chain.
        schema:
          type: string
      - name: expiration
        in: query
        required: false
        description: Filter the chain to a single expiration date.
        schema:
          type: string
      - name: side
        in: query
        required: false
        description: Filter to call or put contracts.
        schema:
          type: string
          enum:
          - call
          - put
      responses:
        '200':
          description: The option chain for the underlying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptionQuoteResponse'
        '203':
          description: Cached option chain (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptionQuoteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /options/quotes/{optionSymbol}/:
    get:
      operationId: getOptionQuote
      tags:
      - Options
      summary: Option quote
      description: Get a real-time or historical (end-of-day) quote for a single option contract identified by its OCC option symbol, including bid, ask, last, volume, open interest, and Greeks.
      parameters:
      - name: optionSymbol
        in: path
        required: true
        description: The OCC option symbol, e.g. AAPL230728C00200000.
        schema:
          type: string
      responses:
        '200':
          description: Quote for the requested option contract.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptionQuoteResponse'
        '203':
          description: Cached option quote (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptionQuoteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    TooManyRequests:
      description: Credit allocation or simultaneous-request limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed or the token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    OptionQuoteResponse:
      type: object
      description: Column-oriented option contract quote payload.
      properties:
        s:
          type: string
          description: Status of the response.
        optionSymbol:
          type: array
          items:
            type: string
        underlying:
          type: array
          items:
            type: string
        expiration:
          type: array
          items:
            type: integer
        side:
          type: array
          items:
            type: string
        strike:
          type: array
          items:
            type: number
        bid:
          type: array
          items:
            type: number
        ask:
          type: array
          items:
            type: number
        last:
          type: array
          items:
            type: number
        openInterest:
          type: array
          items:
            type: integer
        iv:
          type: array
          items:
            type: number
        delta:
          type: array
          items:
            type: number
    ErrorResponse:
      type: object
      properties:
        s:
          type: string
          description: Always error for failed requests.
        errmsg:
          type: string
          description: Human-readable error message.
    GenericResponse:
      type: object
      description: Generic column-oriented Market Data response keyed by status flag s.
      properties:
        s:
          type: string
          description: Status of the response - ok, no_data, or error.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token generated in the Market Data dashboard. Passed as Authorization Bearer YOUR_API_TOKEN. A token may also be supplied via the token query parameter.