openapi: 3.0.3
info:
  title: Market Data Indices Stocks 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: Stocks
  description: Real-time and historical stock candles, quotes, bulk data, earnings, and news.
paths:
  /stocks/candles/{resolution}/{symbol}/:
    get:
      operationId: getStockCandles
      tags:
      - Stocks
      summary: Stock candles
      description: Retrieve open, high, low, close, and volume (OHLCV) candlestick data for a stock over a given date range at the requested resolution (e.g. daily, hourly, or minute intervals).
      parameters:
      - name: resolution
        in: path
        required: true
        description: Candle resolution such as D (daily), W, M, or a minute/hour value.
        schema:
          type: string
      - name: symbol
        in: path
        required: true
        description: The company's ticker symbol.
        schema:
          type: string
      - name: from
        in: query
        required: false
        description: The leftmost (earliest) date of the date range.
        schema:
          type: string
      - name: to
        in: query
        required: false
        description: The rightmost (latest) date of the date range.
        schema:
          type: string
      responses:
        '200':
          description: OHLCV candle series.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandlesResponse'
        '203':
          description: Cached OHLCV candle series (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandlesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stocks/quotes/{symbol}/:
    get:
      operationId: getStockQuote
      tags:
      - Stocks
      summary: Stock quote
      description: Fetch a real-time or historical quote for a single stock symbol, including last price, bid, ask, volume, and change.
      parameters:
      - name: symbol
        in: path
        required: true
        description: The company's ticker symbol.
        schema:
          type: string
      responses:
        '200':
          description: A quote for the requested symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '203':
          description: Cached quote (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stocks/bulkquotes/:
    get:
      operationId: getStockBulkQuotes
      tags:
      - Stocks
      summary: Bulk stock quotes
      description: Fetch real-time quotes for many stock symbols in a single request. Each symbol included in the response consumes credits.
      parameters:
      - name: symbols
        in: query
        required: true
        description: Comma-separated list of ticker symbols.
        schema:
          type: string
      responses:
        '200':
          description: Quotes for the requested symbols.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '203':
          description: Cached bulk quotes (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stocks/bulkcandles/{resolution}/:
    get:
      operationId: getStockBulkCandles
      tags:
      - Stocks
      summary: Bulk stock candles
      description: Fetch candlestick data for many stock symbols at once for a single date at the requested resolution. Each symbol in the response consumes credits.
      parameters:
      - name: resolution
        in: path
        required: true
        description: Candle resolution such as D (daily).
        schema:
          type: string
      - name: symbols
        in: query
        required: true
        description: Comma-separated list of ticker symbols.
        schema:
          type: string
      responses:
        '200':
          description: Candles for the requested symbols.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandlesResponse'
        '203':
          description: Cached bulk candles (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandlesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stocks/earnings/{symbol}/:
    get:
      operationId: getStockEarnings
      tags:
      - Stocks
      summary: Stock earnings
      description: Retrieve reported and estimated earnings data (EPS, report date, fiscal period) for a stock symbol.
      parameters:
      - name: symbol
        in: path
        required: true
        description: The company's ticker symbol.
        schema:
          type: string
      responses:
        '200':
          description: Earnings data for the requested symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '203':
          description: Cached earnings data (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /stocks/news/{symbol}/:
    get:
      operationId: getStockNews
      tags:
      - Stocks
      summary: Stock news
      description: Retrieve news headlines and article links related to a stock symbol.
      parameters:
      - name: symbol
        in: path
        required: true
        description: The company's ticker symbol.
        schema:
          type: string
      responses:
        '200':
          description: News items for the requested symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '203':
          description: Cached news items (treat as success).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    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.
    CandlesResponse:
      type: object
      description: Column-oriented OHLCV candle series.
      properties:
        s:
          type: string
          description: Status of the response - ok, no_data, or error.
        t:
          type: array
          description: Candle timestamps (Unix seconds).
          items:
            type: integer
        o:
          type: array
          description: Open prices.
          items:
            type: number
        h:
          type: array
          description: High prices.
          items:
            type: number
        l:
          type: array
          description: Low prices.
          items:
            type: number
        c:
          type: array
          description: Close prices.
          items:
            type: number
        v:
          type: array
          description: Volume.
          items:
            type: integer
    ErrorResponse:
      type: object
      properties:
        s:
          type: string
          description: Always error for failed requests.
        errmsg:
          type: string
          description: Human-readable error message.
    QuoteResponse:
      type: object
      description: Column-oriented quote payload.
      properties:
        s:
          type: string
          description: Status of the response.
        symbol:
          type: array
          items:
            type: string
        last:
          type: array
          items:
            type: number
        bid:
          type: array
          items:
            type: number
        ask:
          type: array
          items:
            type: number
        volume:
          type: array
          items:
            type: integer
        updated:
          type: array
          items:
            type: integer
  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'
  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.