{"openapi":"3.1.0","info":{"title":"MarketBotsLab API","version":"1.0.0","description":"Public HTTP surface for the MarketBotsLab platform: breakout signals, market data, transparency ledger, and AI explanations. Internal/cron endpoints are intentionally omitted. Protected routes authenticate via the Clerk session cookie.","contact":{"name":"MarketBotsLab SDK","url":"/api-docs/sdk"}},"servers":[{"url":"/","description":"Current deployment (relative)"},{"url":"https://stock-insights.example.com","description":"Production"}],"tags":[{"name":"System","description":"Health, readiness, operational."},{"name":"Market Data","description":"Quotes, bars, sector context."},{"name":"Signals","description":"Breakout detection + ranking."},{"name":"Transparency","description":"Public ledger + performance rollups."},{"name":"Fundamentals","description":"Earnings, float, company facts."},{"name":"AltData","description":"Insider, options flow, short interest."},{"name":"Options","description":"Options strategy analysis."},{"name":"AI","description":"LLM-backed explanations."},{"name":"Backtest","description":"Walk-forward backtesting."},{"name":"Realtime","description":"Server-Sent Events streams."},{"name":"GraphQL","description":"GraphQL endpoint for composed, multi-resource queries."}],"paths":{"/api/health":{"get":{"summary":"Liveness + readiness probe","operationId":"getHealth","tags":["System"],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"503":{"description":"One or more subsystems are down.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/breakouts":{"get":{"summary":"Ranked breakout signals across the universe","operationId":"getBreakouts","tags":["Signals"],"parameters":[{"name":"symbols","in":"query","description":"Comma-separated symbol list. Defaults to server-side universe.","schema":{"type":"string"}},{"name":"timeframe","in":"query","description":"Bar timeframe.","schema":{"type":"string","enum":["daily","4h","1h"],"default":"daily"}},{"name":"view","in":"query","description":"Pass `rollup` to group signals per symbol.","schema":{"type":"string","enum":["rollup"]}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BreakoutsResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Scan failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bars":{"get":{"summary":"Historical OHLCV bars","operationId":"getBars","tags":["Market Data"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"Ticker symbol, e.g. `AAPL`. Case-insensitive.","schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,9}$"}},{"name":"range","in":"query","description":"Lookback range.","schema":{"type":"string","enum":["1mo","3mo","6mo"],"default":"6mo"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BarsResponse"}}}},"400":{"description":"Missing or invalid symbol/range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/scorecard":{"get":{"summary":"Aggregated signal performance scorecard","operationId":"getScorecard","tags":["Transparency"],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScorecardResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/snapshot":{"get":{"summary":"Latest quote snapshot for a symbol","operationId":"getSnapshot","tags":["Market Data"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"Ticker symbol, e.g. `AAPL`. Case-insensitive.","schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,9}$"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotResponse"}}}},"400":{"description":"Missing symbol.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/confluence":{"get":{"summary":"Multi-timeframe confluence for a symbol","operationId":"getConfluence","tags":["Signals"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"Ticker symbol, e.g. `AAPL`. Case-insensitive.","schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,9}$"}},{"name":"timeframe","in":"query","schema":{"type":"string","enum":["daily","4h","1h"],"default":"daily"}},{"name":"lookback","in":"query","description":"Number of bars to consider.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfluenceResponse"}}}},"400":{"description":"Missing symbol or invalid timeframe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/earnings":{"get":{"summary":"Earnings calendar + proximity context","operationId":"getEarnings","tags":["Fundamentals"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"Ticker symbol, e.g. `AAPL`. Case-insensitive.","schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,9}$"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EarningsResponse"}}}},"400":{"description":"Missing symbol.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/sector-rotation":{"get":{"summary":"Sector rotation relative to SPY","operationId":"getSectorRotation","tags":["Market Data"],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SectorRotationResponse"}}}}}}},"/api/float":{"get":{"summary":"Float metrics + volume rotation classification","operationId":"getFloat","tags":["Fundamentals"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"Ticker symbol, e.g. `AAPL`. Case-insensitive.","schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,9}$"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FloatResponse"}}}},"400":{"description":"Missing symbol.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/universe/scan":{"get":{"summary":"Rank the configured universe by relative strength","operationId":"getUniverseScan","tags":["Signals"],"parameters":[{"name":"source","in":"query","description":"Comma-separated universe sources (`sp500`, `nasdaq100`, `high_liquidity`).","schema":{"type":"string","default":"sp500"}},{"name":"benchmark","in":"query","schema":{"type":"string","default":"SPY"}},{"name":"minRsRank","in":"query","schema":{"type":"number","default":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},{"name":"minAvgVolUsd","in":"query","schema":{"type":"number","default":200000000}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UniverseScanResponse"}}}}}}},"/api/transparency/ledger":{"get":{"summary":"Signal ledger — every surfaced signal + outcome","operationId":"getTransparencyLedger","tags":["Transparency"],"parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date"}},{"name":"until","in":"query","schema":{"type":"string","format":"date"}},{"name":"patternType","in":"query","schema":{"type":"string"}},{"name":"scoreBand","in":"query","schema":{"type":"string","enum":["elite","strong","watchlist","ignore"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":500}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/transparency/monthly":{"get":{"summary":"Monthly transparency summary","operationId":"getMonthlySummary","tags":["Transparency"],"parameters":[{"name":"month","in":"query","required":true,"description":"YYYY-MM","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonthlySummaryResponse"}}}},"400":{"description":"Missing or invalid month.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/macro/calendar":{"get":{"summary":"Macroeconomic event calendar (optional endpoint)","description":"May return 404 if the macro service has not been deployed yet.","operationId":"getMacroCalendar","tags":["Market Data"],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MacroCalendarResponse"}}}},"404":{"description":"Macro calendar not available in this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/stream":{"get":{"summary":"Server-Sent Events stream for breakouts and quotes","description":"Long-lived `text/event-stream` connection. Clients subscribe via the `channels` and `symbols` query parameters. A `hello` event is emitted on connect; periodic `: ping` comments keep the connection alive.","operationId":"getStream","tags":["Realtime"],"parameters":[{"name":"channels","in":"query","description":"CSV of pub/sub channels (`breakouts.new`, `breakouts.state_change`, `alerts.dispatched`).","schema":{"type":"string"}},{"name":"symbols","in":"query","description":"CSV of symbols to receive per-symbol quote updates.","schema":{"type":"string"}}],"responses":{"200":{"description":"SSE stream opened.","headers":{"Content-Type":{"schema":{"type":"string","const":"text/event-stream; charset=utf-8"}}},"content":{"text/event-stream":{"schema":{"type":"string","description":"Newline-delimited SSE frames."}}}}}}},"/api/explain":{"get":{"summary":"Natural-language explanation of a signal","operationId":"getExplain","tags":["AI"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"Ticker symbol, e.g. `AAPL`. Case-insensitive.","schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,9}$"}},{"name":"signalId","in":"query","description":"Optional signal id `SYMBOL-pattern-detectedAt`.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainResponse"}}}},"400":{"description":"Missing symbol.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Signal not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"AI context unavailable (no API key / circuit open).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Explain a client-provided signal payload","operationId":"postExplain","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainRequestBody"}}}},"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplainResponse"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"AI context unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/altdata/insider":{"get":{"summary":"Insider transactions + rolling summary","operationId":"getInsider","tags":["AltData"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"Ticker symbol, e.g. `AAPL`. Case-insensitive.","schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,9}$"}},{"name":"windowDays","in":"query","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsiderResponse"}}}},"400":{"description":"Missing symbol.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/altdata/options-flow":{"get":{"summary":"Unusual options volume detector","operationId":"getOptionsFlow","tags":["AltData"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"Ticker symbol, e.g. `AAPL`. Case-insensitive.","schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,9}$"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionsFlowResponse"}}}},"400":{"description":"Missing symbol.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/altdata/short-interest":{"get":{"summary":"Short interest + squeeze-risk classification","operationId":"getShortInterest","tags":["AltData"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"Ticker symbol, e.g. `AAPL`. Case-insensitive.","schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,9}$"}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShortInterestResponse"}}}},"400":{"description":"Missing symbol.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/options/analyze":{"get":{"summary":"Options strategy recommendation for a breakout setup","operationId":"getOptionsAnalyze","tags":["Options"],"parameters":[{"name":"symbol","in":"query","required":true,"description":"Ticker symbol, e.g. `AAPL`. Case-insensitive.","schema":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9.-]{0,9}$"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["long"],"default":"long"}},{"name":"trigger","in":"query","required":true,"schema":{"type":"number"}},{"name":"target","in":"query","required":true,"schema":{"type":"number"}},{"name":"stop","in":"query","schema":{"type":"number"}},{"name":"iv","in":"query","schema":{"type":"number","default":0.3}},{"name":"ivRank","in":"query","schema":{"type":"number"}},{"name":"expiryDays","in":"query","schema":{"type":"integer","default":30}},{"name":"r","in":"query","schema":{"type":"number","default":0.05}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionsAnalyzeResponse"}}}},"400":{"description":"Invalid trigger/target/direction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/graphql":{"get":{"summary":"GraphQL endpoint (GraphiQL UI + introspection via GET)","description":"Sprint-12 GraphQL layer alongside REST. A GET request renders the graphql-yoga GraphiQL IDE. Complex cross-cutting queries (signals + fundamentals + sector rotation in one round-trip) should prefer this endpoint over fanning out to multiple REST routes.","operationId":"getGraphQL","tags":["GraphQL"],"responses":{"200":{"description":"GraphiQL HTML (browser) or GraphQL JSON response.","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Execute a GraphQL query or mutation","description":"Accepts the standard `{ query, variables, operationName }` JSON body. Auth via API key (Bearer) OR Clerk session cookie; mutations are tier-gated.","operationId":"postGraphQL","tags":["GraphQL"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"variables":{"type":"object","additionalProperties":true},"operationName":{"type":"string"}}}}}},"responses":{"200":{"description":"GraphQL execution result.","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true,"nullable":true},"errors":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/backtest/walk-forward":{"post":{"summary":"Run a walk-forward backtest","description":"Walk-forward evaluation with purged folds. This endpoint is exposed as POST in the public catalogue so clients can submit larger configurations; the current implementation also accepts GET with query params for convenience.","operationId":"postWalkForward","tags":["Backtest"],"parameters":[{"name":"symbol","in":"query","schema":{"type":"string","default":"AAPL"}},{"name":"benchmark","in":"query","schema":{"type":"string","default":"SPY"}},{"name":"months","in":"query","schema":{"type":"string","enum":["1","3","6"]}},{"name":"train","in":"query","schema":{"type":"integer","default":60}},{"name":"test","in":"query","schema":{"type":"integer","default":20}},{"name":"purge","in":"query","schema":{"type":"integer","default":2}},{"name":"embargo","in":"query","schema":{"type":"integer","default":2}},{"name":"commission","in":"query","schema":{"type":"number","default":0.005}},{"name":"slippage","in":"query","schema":{"type":"number","default":5}}],"responses":{"200":{"description":"OK","headers":{"X-RateLimit-Limit":{"description":"Request quota ceiling for the current window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer"}},"X-Request-Id":{"description":"Opaque request correlation id, echoed in server logs.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalkForwardResponse"}}}},"400":{"description":"Insufficient bars for requested window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Backtest execution failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"ClerkSession":[]}]}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message."},"requestId":{"type":"string"}}},"PriceBar":{"type":"object","required":["date","open","high","low","close","volume"],"properties":{"date":{"type":"string","format":"date"},"open":{"type":"number"},"high":{"type":"number"},"low":{"type":"number"},"close":{"type":"number"},"volume":{"type":"number"}}},"BarsResponse":{"type":"object","required":["symbol","range","bars"],"properties":{"symbol":{"type":"string"},"range":{"type":"string","enum":["1mo","3mo","6mo"]},"bars":{"type":"array","items":{"$ref":"#/components/schemas/PriceBar"}}}},"BreakoutSignal":{"type":"object","required":["symbol","timeframe","patternType","direction","finalScore"],"properties":{"symbol":{"type":"string"},"timeframe":{"type":"string","enum":["daily","4h","1h"]},"patternFamily":{"type":"string"},"patternType":{"type":"string"},"direction":{"type":"string","enum":["long","short"]},"trendRegime":{"type":"string"},"breakoutState":{"type":"string"},"triggerPrice":{"type":"number"},"target1":{"type":"number"},"stopLoss":{"type":"number","nullable":true},"finalScore":{"type":"number"},"confidence":{"type":"number"},"reasons":{"type":"array","items":{"type":"string"}},"detectedAt":{"type":"string","format":"date-time"}}},"BreakoutsResponse":{"type":"object","required":["rankedSignals","generatedAt"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"rankedSignals":{"type":"array","items":{"$ref":"#/components/schemas/BreakoutSignal"}},"alertCandidates":{"type":"array","items":{"$ref":"#/components/schemas/BreakoutSignal"}},"alertBlocked":{"type":"array","items":{"type":"object"}},"alertThresholds":{"type":"object","additionalProperties":true},"alertSummary":{"type":"object","additionalProperties":true},"latestPersistedRun":{"type":"object","nullable":true,"additionalProperties":true},"runHistory":{"type":"array","items":{"type":"object"}},"view":{"type":"string","enum":["rollup"]},"symbolRollups":{"type":"array","items":{"type":"object"}}}},"ScorecardResponse":{"type":"object","additionalProperties":true,"description":"Aggregated signal performance scorecard; structure evolves with releases."},"HealthResponse":{"type":"object","required":["status","checks","version","timestamp"],"properties":{"status":{"type":"string","enum":["ok","degraded"]},"checks":{"type":"object","properties":{"db":{"type":"string","enum":["ok","down","warn","degraded"]},"dataAdapter":{"type":"string","enum":["ok","down","warn","degraded"]},"env":{"type":"string","enum":["ok","down","warn","degraded"]},"kv":{"type":"string","enum":["ok","down","warn","degraded"]}}},"version":{"type":"string"},"uptime":{"type":"integer","description":"Seconds since process start."},"timestamp":{"type":"string","format":"date-time"}}},"SnapshotResponse":{"type":"object","required":["symbol"],"properties":{"symbol":{"type":"string"},"source":{"type":"string"},"price":{"type":"number"},"volume":{"type":"number"},"ts":{"type":"string"}},"additionalProperties":true},"ConfluenceResponse":{"type":"object","additionalProperties":true,"description":"Multi-timeframe confluence analysis for a symbol."},"EarningsResponse":{"type":"object","required":["symbol"],"properties":{"symbol":{"type":"string"},"calendar":{"type":"array","items":{"type":"object","additionalProperties":true}},"proximity":{"type":"object","additionalProperties":true,"nullable":true}}},"SectorRotationResponse":{"type":"object","required":["asOf","benchmark","count","sectors"],"properties":{"asOf":{"type":"string","format":"date-time"},"benchmark":{"type":"string"},"count":{"type":"integer"},"sectors":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"FloatResponse":{"type":"object","required":["symbol"],"properties":{"symbol":{"type":"string"},"float":{"type":"object","properties":{"shareOutstanding":{"type":"number","nullable":true},"freeFloat":{"type":"number","nullable":true},"asOf":{"type":"string","nullable":true},"source":{"type":"string"}}},"ratio":{"type":"number","nullable":true},"classification":{"type":"string"},"caveat":{"type":"string"}}},"UniverseScanResponse":{"type":"object","required":["ok","generatedAt","ranked"],"properties":{"ok":{"type":"boolean"},"generatedAt":{"type":"string","format":"date-time"},"source":{"type":"string"},"benchmark":{"type":"string"},"universeSize":{"type":"integer"},"regime":{"type":"object","additionalProperties":true},"regimeMultiplier":{"type":"number"},"ranked":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"LedgerResponse":{"type":"object","required":["count","filters","records"],"properties":{"count":{"type":"integer"},"filters":{"type":"object","additionalProperties":true},"records":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"MonthlySummaryResponse":{"type":"object","additionalProperties":true,"description":"Monthly transparency rollup for a given YYYY-MM."},"ExplainResponse":{"type":"object","required":["symbol","bullets"],"properties":{"symbol":{"type":"string"},"patternType":{"type":"string"},"bullets":{"type":"array","items":{"type":"string"}},"modelUsed":{"type":"string"},"cacheHitRatio":{"type":"number"}}},"ExplainRequestBody":{"type":"object","required":["signal"],"properties":{"signal":{"$ref":"#/components/schemas/BreakoutSignal"},"news":{"type":"array","items":{"type":"object","additionalProperties":true}},"sectorCtx":{"type":"object","additionalProperties":true}}},"InsiderResponse":{"type":"object","required":["symbol","transactions"],"properties":{"symbol":{"type":"string"},"summary":{"type":"object","additionalProperties":true},"transactions":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"OptionsFlowResponse":{"type":"object","required":["symbol","flow"],"properties":{"symbol":{"type":"string"},"flow":{"type":"object","additionalProperties":true}}},"ShortInterestResponse":{"type":"object","required":["symbol"],"properties":{"symbol":{"type":"string"},"snapshot":{"type":"object","nullable":true,"additionalProperties":true},"squeezeRisk":{"type":"string","enum":["low","moderate","elevated","high"]}}},"OptionsAnalyzeResponse":{"type":"object","required":["symbol","direction","recommendation"],"properties":{"symbol":{"type":"string"},"direction":{"type":"string"},"inputs":{"type":"object","additionalProperties":true},"recommendation":{"type":"object","additionalProperties":true}}},"WalkForwardResponse":{"type":"object","required":["symbol","metrics","tradeCount"],"properties":{"symbol":{"type":"string"},"benchmark":{"type":"string"},"range":{"type":"string"},"config":{"type":"object","additionalProperties":true},"folds":{"type":"array","items":{"type":"object","additionalProperties":true}},"tradeCount":{"type":"integer"},"metrics":{"type":"object","additionalProperties":true},"benchmarks":{"type":"object","additionalProperties":true},"scoreBands":{"type":"object","additionalProperties":true},"disclaimer":{"type":"string"}}},"MacroCalendarResponse":{"type":"object","additionalProperties":true,"description":"Upcoming macroeconomic events (FOMC, CPI, NFP...). May not be deployed yet."},"PageMeta":{"type":"object","required":["nextCursor","hasMore","limit","offset","order"],"properties":{"nextCursor":{"type":["string","null"],"description":"Pass back as `cursor` to fetch the next page, or `null` when this is the last page."},"hasMore":{"type":"boolean","description":"`true` when another page exists."},"total":{"type":"integer","description":"Total rows matching the query when cheap to compute; omitted otherwise."},"limit":{"type":"integer"},"offset":{"type":"integer"},"order":{"type":"string","enum":["asc","desc"]}}}},"securitySchemes":{"ClerkSession":{"type":"apiKey","in":"cookie","name":"__session","description":"Clerk session cookie. Required on protected routes (backtests, write endpoints). Read-only public routes are IP-rate-limited."}}}}