{
  "openapi": "3.1.0",
  "info": {
    "title": "HistoricalData.net Catalog API",
    "version": "1.0.0",
    "description": "Free metadata API for HistoricalData.net - bulk historical U.S. stock and options data sold as downloadable CSV bundles. This API exposes dataset coverage, per-symbol availability and pricing only; the datasets themselves are paid downloads. Rate limit: 30 requests/minute per IP. Single-symbol lookups only (no bulk listing). An MCP endpoint with the same capabilities is available at https://historicaldata.net/mcp (Streamable HTTP). Docs: https://historicaldata.net/ai.html",
    "contact": { "email": "info@historicaldata.net", "url": "https://historicaldata.net" }
  },
  "servers": [{ "url": "https://historicaldata.net" }],
  "paths": {
    "/api/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Current data freshness",
        "description": "Returns how far each dataset currently extends (stock bundle date, latest options EOD date) and ticker counts.",
        "responses": {
          "200": {
            "description": "Freshness summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "generated": { "type": "string", "format": "date-time" },
                    "stocks": {
                      "type": "object",
                      "properties": {
                        "lastDate": { "type": "string", "description": "Date the currently sold stock bundle extends to (YYYY-MM-DD)" },
                        "activeCount": { "type": "integer" },
                        "delistedCount": { "type": "integer" }
                      }
                    },
                    "options": {
                      "type": "object",
                      "properties": {
                        "latestDate": { "type": "string", "description": "Latest options EOD file date (YYYY-MM-DD)" },
                        "underlyingCount": { "type": "integer" },
                        "archiveMonths": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/symbol/{ticker}": {
      "get": {
        "operationId": "lookupSymbol",
        "summary": "Check coverage for one symbol",
        "description": "Returns whether the ticker is included in the stock dataset (with per-company records when a symbol was reused, coverage dates, active/delisted status, file sizes) and whether options data exists for it as an underlying.",
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,15}$" },
            "example": "AAPL"
          }
        ],
        "responses": {
          "200": {
            "description": "Symbol coverage report",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ticker": { "type": "string" },
                    "stocks": {
                      "type": "object",
                      "properties": {
                        "found": { "type": "boolean" },
                        "lastDate": { "type": "string" },
                        "records": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "type": { "type": "string", "description": "Security type: CS, ETF, ADRC, PFD, WARRANT, ..." },
                              "active": { "type": "boolean" },
                              "delistDate": { "type": ["string", "null"] },
                              "coverage": { "type": "string", "description": "start / end dates" },
                              "sizeDayBytes": { "type": "integer" },
                              "sizeMinuteRegularBytes": { "type": "integer" },
                              "sizeMinuteExtendedBytes": { "type": "integer" }
                            }
                          }
                        }
                      }
                    },
                    "options": {
                      "type": "object",
                      "properties": {
                        "found": { "type": "boolean" },
                        "latestDate": { "type": "string" },
                        "contractsLatestDay": { "type": "integer" },
                        "coverage": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": { "description": "Rate limited (30 requests/minute per IP)" }
        }
      }
    },
    "/api/catalog": {
      "get": {
        "operationId": "getCatalog",
        "summary": "Dataset catalog",
        "description": "Lists the datasets for sale with live coverage ranges, update cadence, ticker counts, bundle sizes, prices and purchase links.",
        "responses": {
          "200": { "description": "Catalog of datasets with prices and purchase links" }
        }
      }
    }
  }
}