{
  "openapi": "3.0.3",
  "info": {
    "title": "BAKO API",
    "description": "Financial data and ML-powered price predictions API for 40,000+ stocks, ETFs, and cryptocurrencies.",
    "version": "1.0.0",
    "contact": {
      "name": "BAKO API Support",
      "email": "api@bako.co",
      "url": "https://api.bako.co"
    }
  },
  "servers": [
    {
      "url": "https://api.bako.co/v1",
      "description": "Production API Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "api-key",
        "description": "API key generated in your BAKO API dashboard"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Invalid or missing API key. Include api-key header."
          }
        },
        "required": ["error"]
      },
      "RateLimitErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "Rate limit exceeded. Upgrade your plan for more requests."
          },
          "todayUsage": {
            "type": "integer",
            "example": 101
          }
        },
        "required": ["error"]
      },
      "SymbolItem": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "example": "NVDA" },
          "type": { "type": "string", "example": "Stock" },
          "exchange": { "type": "string", "example": "NASDAQ" },
          "startDate": { "type": "string", "format": "date", "example": "1999-01-22" },
          "endDate": { "type": "string", "format": "date", "example": "2026-10-14" }
        },
        "required": ["symbol", "type"]
      },
      "SymbolsResponse": {
        "type": "object",
        "properties": {
          "total": { "type": "integer", "example": 40225 },
          "limit": { "type": "integer", "example": 100 },
          "offset": { "type": "integer", "example": 0 },
          "count": { "type": "integer", "example": 2 },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/SymbolItem" }
          }
        },
        "required": ["total", "limit", "offset", "count", "data"]
      },
      "PricePoint": {
        "type": "object",
        "properties": {
          "date": { "type": "string", "format": "date", "example": "2026-10-14" },
          "price": { "type": "number", "format": "float", "example": 138.25 }
        },
        "required": ["date", "price"]
      },
      "HistoryResponse": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "example": "NVDA" },
          "count": { "type": "integer", "example": 500 },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PricePoint" }
          }
        },
        "required": ["symbol", "count", "data"]
      },
      "PredictionsResponse": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "example": "NVDA" },
          "predictionDate": { "type": "string", "format": "date", "example": "2026-10-14" },
          "horizon": { "type": "integer", "example": 100 },
          "count": { "type": "integer", "example": 100 },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PricePoint" }
          }
        },
        "required": ["symbol", "predictionDate", "horizon", "count", "data"]
      }
    }
  },
  "paths": {
    "/symbols": {
      "get": {
        "summary": "Search and list symbols",
        "description": "Browse and search 40,000+ available stocks, ETFs, and cryptocurrencies. Free public endpoint, no API key required.",
        "operationId": "getSymbols",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by asset class: stock, etf, or crypto. Omit for all types.",
            "schema": {
              "type": "string",
              "enum": ["stock", "etf", "crypto"]
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Case-insensitive ticker substring search (e.g. NVD matches NVDA, NVDL).",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results to return (default 100, max 1000).",
            "schema": { "type": "integer", "default": 100, "maximum": 1000 }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Number of records to skip for pagination (default 0).",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching symbols list with pagination metadata",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SymbolsResponse" }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/history": {
      "get": {
        "summary": "Get historical daily closing prices",
        "description": "Retrieve daily close prices from first listing to today. Requires an API key.",
        "operationId": "getHistory",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "symbol",
            "in": "query",
            "required": true,
            "description": "Ticker symbol (e.g. NVDA, AAPL, btcusd).",
            "schema": { "type": "string" }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Asset category (stock or crypto).",
            "schema": { "type": "string", "enum": ["stock", "crypto"] }
          },
          {
            "name": "startDate",
            "in": "query",
            "required": false,
            "description": "Earliest date in YYYY-MM-DD format.",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "endDate",
            "in": "query",
            "required": false,
            "description": "Latest date in YYYY-MM-DD format.",
            "schema": { "type": "string", "format": "date" }
          }
        ],
        "responses": {
          "200": {
            "description": "Historical price array",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HistoryResponse" }
              }
            }
          },
          "400": {
            "description": "Missing required symbol parameter",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "404": {
            "description": "Symbol not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Daily rate limit exceeded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/predictions": {
      "get": {
        "summary": "Get machine-learning price predictions",
        "description": "Returns forward daily price predictions up to 100 days into the future. Requires an API key.",
        "operationId": "getPredictions",
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "symbol",
            "in": "query",
            "required": true,
            "description": "Ticker symbol (e.g. NVDA, AAPL, btcusd).",
            "schema": { "type": "string" }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Asset category (stock or crypto).",
            "schema": { "type": "string", "enum": ["stock", "crypto"] }
          },
          {
            "name": "predictionDate",
            "in": "query",
            "required": false,
            "description": "Historical forecast run date (YYYY-MM-DD). Defaults to latest.",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "startDate",
            "in": "query",
            "required": false,
            "description": "Filter prediction dates starting from YYYY-MM-DD.",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "endDate",
            "in": "query",
            "required": false,
            "description": "Filter prediction dates up to YYYY-MM-DD.",
            "schema": { "type": "string", "format": "date" }
          }
        ],
        "responses": {
          "200": {
            "description": "Prediction time series with horizon",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PredictionsResponse" }
              }
            }
          },
          "400": {
            "description": "Missing required symbol parameter",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "404": {
            "description": "Prediction not found for symbol",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Daily rate limit exceeded",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RateLimitErrorResponse" }
              }
            }
          }
        }
      }
    }
  }
}