{
  "openapi": "3.1.0",
  "info": {
    "title": "OptionData HTTP APIs",
    "version": "1.0.0",
    "summary": "OPRA-licensed U.S. equity options data — historical SQL, option chain, market structure",
    "description": "OptionData (optiondata.io) provides OPRA-licensed U.S. equity options data.\n\nPro list price $599/month; 14-day free trial.\n\nRealtime trades stream over WebSocket at wss://ws.optiondata.io (see /docs/realtime-option-trades-api/).\n\nHuman docs: /docs/ · AI map: /llms.txt",
    "contact": {
      "name": "OptionData Support",
      "email": "support@optiondata.io",
      "url": "https://www.optiondata.io"
    },
    "license": {
      "name": "Proprietary — OPRA-licensed data product",
      "url": "https://www.optiondata.io/terms-of-service/"
    }
  },
  "servers": [
    {
      "url": "https://www.optiondata.io",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Historical SQL",
      "description": "ClickHouse SELECT over historical option trades"
    },
    {
      "name": "Option Chain",
      "description": "Full option chain snapshots via REST"
    },
    {
      "name": "Market Structure",
      "description": "GEX / dealer-positioning symbol snapshots"
    }
  ],
  "paths": {
    "/api/historical/sql": {
      "post": {
        "tags": [
          "Historical SQL"
        ],
        "summary": "Execute a guarded historical SQL query",
        "description": "Run a SELECT-only ClickHouse query against whitelisted option-trade tables. Requires an API key. Trial responses are row-capped.",
        "operationId": "historicalSql",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HistoricalSqlRequest"
              },
              "example": {
                "api_key": "apikey_YOUR_KEY",
                "sql": "SELECT symbol, strike, put_call, size, price FROM RawOptionTrades WHERE date = today() AND symbol = 'AAPL' LIMIT 10"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/HistoricalSqlRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Query succeeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HistoricalSqlSuccess"
                }
              }
            }
          },
          "400": {
            "description": "Invalid body or SQL rejected by guardrails"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Not entitled"
          },
          "429": {
            "description": "Rate limited"
          },
          "500": {
            "description": "Server error"
          },
          "504": {
            "description": "Query timeout"
          }
        }
      }
    },
    "/api/option-chain": {
      "post": {
        "tags": [
          "Option Chain"
        ],
        "summary": "Fetch an option chain for a symbol",
        "description": "Returns call/put contracts across strikes and expirations for a trading date (latest or explicit). Included with trialing/active realtime.",
        "operationId": "optionChain",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OptionChainRequest"
              },
              "example": {
                "api_key": "apikey_YOUR_KEY",
                "symbol": "AAPL",
                "include_flow": false
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/OptionChainRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chain returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OptionChainSuccess"
                }
              }
            }
          },
          "400": {
            "description": "Validation error"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Not entitled"
          },
          "429": {
            "description": "Rate limited"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    },
    "/api/v1/market-structure/{symbol}": {
      "get": {
        "tags": [
          "Market Structure"
        ],
        "summary": "Fetch market-structure (GEX) snapshot for a symbol",
        "operationId": "marketStructure",
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "SPY"
            },
            "description": "Underlying option root"
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2026-07-24"
            },
            "description": "Retained historical snapshot date; omit for active snapshot"
          },
          {
            "name": "Authorization",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "example": "Bearer apikey_YOUR_KEY"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketStructureSuccess"
                }
              }
            }
          },
          "400": {
            "description": "Invalid symbol or date"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Not entitled"
          },
          "404": {
            "description": "Snapshot not found"
          },
          "429": {
            "description": "Rate limited"
          },
          "500": {
            "description": "Server error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Bearer token: `Authorization: Bearer <api_key>` where api_key is `cus_...` or `apikey_...`."
      },
      "ApiKeyBody": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key-Via-Body",
        "description": "Many endpoints also accept `api_key` in the JSON/form body. Prefer Authorization when possible."
      }
    },
    "schemas": {
      "HistoricalSqlRequest": {
        "type": "object",
        "required": [
          "sql"
        ],
        "properties": {
          "api_key": {
            "type": "string",
            "description": "cus_... or apikey_... (optional if session auth is present)"
          },
          "sql": {
            "type": "string",
            "description": "SELECT-only SQL against whitelisted tables (e.g. RawOptionTrades)"
          },
          "test_mode": {
            "type": "boolean",
            "description": "When true, returns sample rows without querying ClickHouse"
          }
        }
      },
      "HistoricalSqlSuccess": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "SUCCESS"
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "OptionChainRequest": {
        "type": "object",
        "required": [
          "symbol"
        ],
        "properties": {
          "api_key": {
            "type": "string"
          },
          "symbol": {
            "type": "string",
            "example": "AAPL"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "expiration_date": {
            "type": "string",
            "format": "date"
          },
          "put_call": {
            "type": "string",
            "enum": [
              "CALL",
              "PUT"
            ]
          },
          "strike": {
            "type": "number"
          },
          "strike_min": {
            "type": "number"
          },
          "strike_max": {
            "type": "number"
          },
          "include_flow": {
            "type": "boolean",
            "default": false
          },
          "limit": {
            "type": "integer"
          },
          "test_mode": {
            "type": "boolean"
          }
        }
      },
      "OptionChainSuccess": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "SUCCESS"
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "MarketStructureSuccess": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "symbol": {
                "type": "string"
              },
              "symbol_meta": {
                "type": "object",
                "additionalProperties": true
              },
              "flow": {
                "type": "object",
                "additionalProperties": true
              },
              "structure": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "meta": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Full human-readable API docs",
    "url": "https://www.optiondata.io/docs/"
  }
}