{"openapi":"3.1.0","info":{"title":"Forecite API","version":"1.0.0","description":"Low-latency scored news + filings feed. Authenticate with `Authorization: Bearer fc_live_...`."},"servers":[{"url":"https://api.forecite.dev","description":"Production"},{"url":"http://localhost:3000/api","description":"Local dev"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/feeds":{"get":{"summary":"List scored feed items","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Lower bound on published_at"},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"},"description":"Upper bound on published_at"},{"name":"aggregator","in":"query","schema":{"type":"string"},"description":"Filter by source (e.g. globenewswire)"},{"name":"actionability","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"sentiment_min","in":"query","schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"sentiment_max","in":"query","schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"exchange","in":"query","schema":{"type":"string"},"description":"e.g. NASDAQ, NYSE"},{"name":"symbol","in":"query","schema":{"type":"string"},"description":"Short symbol, e.g. TSLA"},{"name":"corp_activity","in":"query","schema":{"type":"string"},"description":"Tag filter — comma-separated values (OR within). See GET /v1/tags."},{"name":"market","in":"query","schema":{"type":"string"},"description":"Tag filter — comma-separated values (OR within). See GET /v1/tags."},{"name":"market_country","in":"query","schema":{"type":"string"},"description":"Tag filter by country. Accepts any ISO 3166-1 alpha-2 code, comma-separated (e.g. US,AE) — not limited to the codes GET /v1/tags returns (those are only countries with data). AND across tag dimensions."},{"name":"economic_category","in":"query","schema":{"type":"string"},"description":"Tag filter — comma-separated values (OR within). See GET /v1/tags."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1},"description":"Capped by tier"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque pagination cursor"}],"responses":{"200":{"description":"Paginated list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedList"}}}},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate-limit exceeded"}}}},"/v1/feeds/{id}":{"get":{"summary":"Fetch one feed item with full detail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Full feed object with per-symbol analysis"},"404":{"description":"Not found"}}}},"/v1/me":{"get":{"summary":"Current API key info: tier, usage, limits","responses":{"200":{"description":"Key metadata"}}}},"/v1/usage":{"get":{"summary":"This key's daily usage (feed vs. score) + limits","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90},"description":"Lookback window (default 30)"}],"responses":{"200":{"description":"Usage history + today's totals"}}}},"/v1/providers":{"get":{"summary":"List news providers (id, name, logo)","responses":{"200":{"description":"Provider list"}}}},"/v1/providers/{id}":{"get":{"summary":"Fetch one provider","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Provider"},"404":{"description":"Not found"}}}},"/v1/sources":{"get":{"summary":"List distinct aggregators (feed sources)","responses":{"200":{"description":"Aggregator names"}}}},"/v1/sources/{name}":{"get":{"summary":"Fetch one source with activity (feed count + latest)","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Source"},"404":{"description":"Not found"}}}},"/v1/symbols":{"get":{"summary":"List tracked tickers (short_symbol, logo)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":2000},"description":"Max symbols (default 500)"}],"responses":{"200":{"description":"Ticker list"}}}},"/v1/symbols/{ticker}":{"get":{"summary":"Fetch one ticker (metadata + feed count)","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string"},"description":"Short symbol, e.g. TSLA"}],"responses":{"200":{"description":"Symbol"},"404":{"description":"Not found"}}}},"/v1/tags":{"get":{"summary":"Tag dictionary grouped by dimension (with labels)","responses":{"200":{"description":"Tags by dimension"}}}},"/v1/tags/{dimension}":{"get":{"summary":"Values for one tag dimension","parameters":[{"name":"dimension","in":"path","required":true,"schema":{"type":"string","enum":["corp_activity","market","market_country","economic_category"]}}],"responses":{"200":{"description":"Tag values"},"400":{"description":"Unknown dimension"}}}},"/v1/score":{"post":{"summary":"Score an artifact with the Verdict Engine (Pro+; per-day quota)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["artifact"],"properties":{"artifact":{"type":"object","required":["type","title","body"],"properties":{"type":{"type":"string","enum":["news","filing","research","ugc"]},"title":{"type":"string"},"body":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"related_symbols":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time"}}},"options":{"type":"object","properties":{"model":{"type":"string","enum":["flash","pro"]},"include_detailed_analysis":{"type":"boolean"},"score_sentiment":{"type":"string","enum":["always","if_actionable"]}}}}}}}},"responses":{"200":{"description":"Verdict (actionability + sentiment)"},"403":{"description":"Scoring not available on this plan"},"429":{"description":"Daily scoring quota exceeded"}}}},"/v1/webhooks":{"get":{"summary":"List webhook endpoints","responses":{"200":{"description":"Webhook list (no secrets)"}}},"post":{"summary":"Register a webhook endpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Created webhook (with signing secret)"},"400":{"description":"Invalid URL"}}}},"/v1/webhooks/{id}":{"get":{"summary":"Fetch one webhook (with secret)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook"},"404":{"description":"Not found"}}},"patch":{"summary":"Update url / description / enabled","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated webhook"},"404":{"description":"Not found"}}},"delete":{"summary":"Delete a webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"},"404":{"description":"Not found"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"fc_live_..."}},"schemas":{"FeedList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedItem"}},"next_cursor":{"type":["string","null"]}}},"FeedItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"unique_id":{"type":"string"},"title":{"type":["string","null"]},"link":{"type":["string","null"]},"source":{"type":"string"},"published_at":{"type":"string","format":"date-time"},"scraped_at":{"type":"string","format":"date-time"},"scoring":{"type":"object","properties":{"actionability":{"type":["boolean","null"]},"actionability_comment":{"type":["string","null"]},"sentiment_score":{"type":["integer","null"],"minimum":0,"maximum":10},"sentiment_comment":{"type":["string","null"]}}},"symbols":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"exchange":{"type":["string","null"]},"short_symbol":{"type":["string","null"]},"logoid":{"type":["string","null"]}}}}}}}}}