{"openapi":"3.1.0","info":{"title":"Intelligence API","version":"1.0.0","description":"Real-time event-driven market intelligence. Government contracts, regulatory disclosures, macro signals and alternative data — organized into intelligence feeds, scored, and surfaced before the market notices."},"servers":[{"url":"https://intelligence-beryl.vercel.app","description":"Production"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"bearer":{"type":"http","scheme":"bearer","bearerFormat":"iv_live_*"}}},"security":[{"apiKey":[]},{"bearer":[]}],"tags":[{"name":"events","description":"Contract events + their latest signals"},{"name":"signals","description":"Engine-produced scores"},{"name":"companies","description":"Issuer-side metadata"},{"name":"market","description":"OHLCV candles + benchmarks"},{"name":"regimes","description":"Macro regime classification (Intelligence+)"},{"name":"predictions","description":"Forward forecasts (Phase 5)"},{"name":"meta","description":"Health, usage, OpenAPI"}],"paths":{"/api/v1/health":{"get":{"operationId":"health","summary":"Service health","description":"Returns DB connectivity and registered engine versions. Open endpoint — no API key required.","tags":["meta"],"responses":{"200":{"description":"Service is up","content":{"application/json":{"example":{"ok":true,"db":{"ok":true},"engines":[{"name":"simple","version":"0.1.0","tier":"simple"}],"now":"2026-05-13T14:02:17.216Z"}}}}},"x-tier":"free","x-scope":"read"}},"/api/v1/events":{"get":{"operationId":"list-events","summary":"List events","description":"Paginated list of contract events ranked by award date, with the latest signal for each contract joined in. Alias of `/api/v1/contracts`.","tags":["events"],"parameters":[{"name":"engine","in":"query","required":false,"description":"Engine name","schema":{"type":"string"},"example":"simple"},{"name":"ticker","in":"query","required":false,"description":"Filter by ticker","schema":{"type":"string"},"example":"LMT"},{"name":"agency","in":"query","required":false,"description":"Filter by awarding agency","schema":{"type":"string"}},{"name":"classification","in":"query","required":false,"description":"NLP classification","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Award date ≥","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Award date ≤","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"description":"1-200, default 50","schema":{"type":"integer"},"example":10},{"name":"offset","in":"query","required":false,"description":"pagination offset, default 0","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of events with embedded latest signal","content":{"application/json":{"example":{"data":[{"contract":{"id":"CONT_AWD_N0001925C0070_9700_-NONE-_-NONE-","ticker":"LMT","recipient_name":"LOCKHEED MARTIN CORPORATION","award_date":"2024-11-22","contract_value":3130421242,"awarding_agency":"Department of Defense","nlp_classification":"Defense escalation","match_confidence":1},"signal":{"id":"8e728629-a546-436d-b483-a7dfb47f0c90","contract_id":"CONT_AWD_N0001925C0070_9700_-NONE-_-NONE-","engine_name":"simple","engine_version":"0.1.0","engine_tier":"simple","signal_score":67,"importance_score":91,"confidence_score":100,"risk_score":21,"computed_at":"2026-05-12T13:56:18.123Z"}}],"pagination":{"limit":10,"offset":0,"count":1}}}}}},"x-tier":"developer","x-scope":"read"}},"/api/v1/contracts":{"get":{"operationId":"list-contracts","summary":"List contracts","description":"Same as `/api/v1/events` — kept for backwards compatibility.","tags":["events"],"parameters":[{"name":"engine","in":"query","required":false,"description":"Engine name","schema":{"type":"string"},"example":"simple"},{"name":"ticker","in":"query","required":false,"description":"Filter by ticker","schema":{"type":"string"},"example":"LMT"},{"name":"limit","in":"query","required":false,"description":"1-200, default 50","schema":{"type":"integer"},"example":10}],"responses":{"200":{"description":"See `/api/v1/events`"}},"x-tier":"developer","x-scope":"read"}},"/api/v1/contracts/{id}":{"get":{"operationId":"get-contract","summary":"Get a single contract","description":"Full contract row with weekly prices, regime, and decay signals.","tags":["events"],"parameters":[{"name":"id","in":"path","required":true,"description":"Contract id (e.g. CONT_AWD_...)","schema":{"type":"string"}}],"responses":{"200":{"description":"Contract bundle","content":{"application/json":{"example":{"contract":{"id":"CONT_AWD_N0001925C0070_9700_-NONE-_-NONE-","ticker":"LMT","recipient_name":"LOCKHEED MARTIN CORPORATION","award_date":"2024-11-22","contract_value":3130421242,"awarding_agency":"Department of Defense","nlp_classification":"Defense escalation","match_confidence":1},"weekly_prices":[],"regime":null,"decay":null}}}},"404":{"description":"Contract not found"}},"x-tier":"developer","x-scope":"read"}},"/api/v1/contracts/{id}/score":{"get":{"operationId":"get-contract-score","summary":"Get the latest signal for a contract","description":"Returns the most recent signal for the contract under the given engine. Includes per-rule rationale on Intelligence-tier and above.","tags":["events"],"parameters":[{"name":"id","in":"path","required":true,"description":"Contract id","schema":{"type":"string"}},{"name":"engine","in":"query","required":false,"description":"Engine name","schema":{"type":"string"},"example":"simple"}],"responses":{"200":{"description":"Signal","content":{"application/json":{"example":{"signal":{"id":"8e728629-a546-436d-b483-a7dfb47f0c90","contract_id":"CONT_AWD_N0001925C0070_9700_-NONE-_-NONE-","engine_name":"simple","engine_version":"0.1.0","engine_tier":"simple","signal_score":67,"importance_score":91,"confidence_score":100,"risk_score":21,"computed_at":"2026-05-12T13:56:18.123Z"}}}}},"404":{"description":"No signal for this engine on this contract"}},"x-tier":"developer","x-scope":"read"},"post":{"operationId":"compute-contract-score","summary":"Compute / recompute a contract score","description":"Idempotent on (contract_id, engine_name, engine_version). Requires `write` scope.","tags":["events"],"parameters":[{"name":"id","in":"path","required":true,"description":"Contract id","schema":{"type":"string"}},{"name":"engine","in":"query","required":false,"description":"Engine name","schema":{"type":"string"},"example":"simple"}],"responses":{"200":{"description":"Updated signal","content":{"application/json":{"example":{"signal":{"id":"8e728629-a546-436d-b483-a7dfb47f0c90","contract_id":"CONT_AWD_N0001925C0070_9700_-NONE-_-NONE-","engine_name":"simple","engine_version":"0.1.0","engine_tier":"simple","signal_score":67,"importance_score":91,"confidence_score":100,"risk_score":21,"computed_at":"2026-05-12T13:56:18.123Z"}}}}},"403":{"description":"Insufficient scope"}},"x-tier":"developer","x-scope":"write"}},"/api/v1/signals":{"get":{"operationId":"list-signals","summary":"List signals (high-score feed)","description":"Paginated list of signals ranked by `signal_score`. Filter by ticker, since timestamp, and minimum score.","tags":["signals"],"parameters":[{"name":"engine","in":"query","required":false,"description":"Engine name","schema":{"type":"string"},"example":"simple"},{"name":"min_score","in":"query","required":false,"description":"Minimum signal score","schema":{"type":"integer"},"example":70},{"name":"ticker","in":"query","required":false,"description":"Filter by ticker","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Lower bound on `computed_at`","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"description":"1-200, default 50","schema":{"type":"integer"},"example":10},{"name":"offset","in":"query","required":false,"description":"pagination offset","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of signals with their joined contracts"}},"x-tier":"developer","x-scope":"read"}},"/api/v1/companies/{ticker}":{"get":{"operationId":"get-company","summary":"Get company + recent contracts","description":"Returns the company record plus the 20 most recent contracts mapped to that ticker.","tags":["companies"],"parameters":[{"name":"ticker","in":"path","required":true,"description":"Stock ticker (e.g. LMT)","schema":{"type":"string"},"example":"LMT"}],"responses":{"200":{"description":"Company + contracts"},"404":{"description":"Unknown ticker"}},"x-tier":"developer","x-scope":"read"}},"/api/v1/market/candles/{ticker}":{"get":{"operationId":"market-candles","summary":"Daily OHLCV candles","description":"Daily OHLCV candles. Phase 1 only has SPY/XLI/ITA seeded; Phase 1.5 adds live FMP coverage for any ticker.","tags":["market"],"parameters":[{"name":"ticker","in":"path","required":true,"description":"Ticker (SPY, XLI, ITA today)","schema":{"type":"string"},"example":"SPY"},{"name":"from","in":"query","required":false,"description":"Lower bound","schema":{"type":"string","format":"date"},"example":"2025-01-01"},{"name":"to","in":"query","required":false,"description":"Upper bound","schema":{"type":"string","format":"date"},"example":"2025-01-31"},{"name":"limit","in":"query","required":false,"description":"≤ 5000, default 500","schema":{"type":"integer"}}],"responses":{"200":{"description":"OHLCV array"}},"x-tier":"developer","x-scope":"read"}},"/api/v1/regimes":{"get":{"operationId":"list-regimes","summary":"Macro regime classifications","description":"Per-contract regime features + scores. Available on Intelligence and above.","tags":["regimes"],"parameters":[{"name":"contract_id","in":"query","required":false,"description":"Specific contract","schema":{"type":"string"}},{"name":"dominant","in":"query","required":false,"description":"Filter by dominant regime","schema":{"type":"string"},"example":"defense_rotation"},{"name":"limit","in":"query","required":false,"description":"1-200, default 50","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of regime classifications"}},"x-tier":"intelligence","x-scope":"read"}},"/api/v1/predictions":{"get":{"operationId":"list-predictions","summary":"Forward predictions (Phase 5)","description":"Probabilistic predictions. Endpoint exists and is rate-limited; the prediction engine ships in Phase 5. Today returns an empty set with a `note` field so client integrations stay green.","tags":["predictions"],"responses":{"200":{"description":"Predictions (currently empty)"}},"x-tier":"intelligence","x-scope":"read"}},"/api/v1/benchmarks":{"get":{"operationId":"get-benchmarks","summary":"Benchmark OHLCV","description":"Daily OHLCV for benchmarks (SPY / XLI / ITA today).","tags":["market"],"parameters":[{"name":"ticker","in":"query","required":true,"description":"Benchmark ticker","schema":{"type":"string"},"example":"SPY"},{"name":"from","in":"query","required":false,"description":"Lower bound","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Upper bound","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OHLCV array"}},"x-tier":"developer","x-scope":"read"}},"/api/v1/usage":{"get":{"operationId":"get-usage","summary":"Your API usage","description":"Returns request and error counts for the calling key over the requested window. Use to self-monitor your budget.","tags":["meta"],"parameters":[{"name":"window","in":"query","required":false,"description":"Bucket window","schema":{"type":"string"},"example":"24h"}],"responses":{"200":{"description":"Usage rollup"}},"x-tier":"developer","x-scope":"read"}},"/api/v1/openapi.json":{"get":{"operationId":"get-openapi","summary":"OpenAPI 3.1 spec","description":"Machine-readable spec of every endpoint. Open — no key required. Use to generate clients.","tags":["meta"],"responses":{"200":{"description":"OpenAPI 3.1 document"}},"x-tier":"free","x-scope":"read"}}}}