{"openapi":"3.1.0","paths":{"/v1/signals/latest":{"get":{"description":"Cursor-paginated list of the most recent scored insider trading signals. Default lookback is 30 days. Every signal carries a composite_score (0-100) plus latency metadata measuring the elapsed time from SEC publication to scoring.","operationId":"SignalsController_getLatest","parameters":[{"name":"X-Request-ID","in":"header","description":"Optional client-supplied trace id. Echoed in response headers and error envelopes.","required":false,"schema":{"type":"string"}},{"name":"FilingIQ-Version","in":"header","description":"Pin the response shape to a specific FilingIQ-Version (YYYY-MM-DD). Documentation-only in v1; routing on this header lands with v2.","required":false,"schema":{"type":"string"}},{"name":"expand","required":false,"in":"query","description":"Comma-separated expansions: filer, company, latency.","schema":{"type":"string"}},{"name":"min_score","required":false,"in":"query","description":"Minimum composite score, 0 to 100.","schema":{"type":"number"}},{"name":"ticker","required":false,"in":"query","description":"Comma-separated ticker filter, e.g. NVDA,AMD.","schema":{"type":"string"}},{"name":"starting_after","required":false,"in":"query","description":"Pagination cursor from a previous response's next_cursor.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Items per page. 1 to 100. Default 25.","schema":{"example":25,"type":"number"}}],"responses":{"200":{"description":"Signal list envelope with cursor pagination."},"400":{"description":"Invalid request parameters."},"401":{"description":"Authentication failed."},"403":{"description":"Tier does not include API access."},"429":{"description":"Rate-limited. Honor the Retry-After response header."}},"security":[{"ApiKey":[]}],"summary":"List most recent scored signals","tags":["Signals"]}},"/v1/signals/high-conviction":{"get":{"description":"Server-filtered view of signals scoring 75 or above. Same envelope shape as /v1/signals/latest with a fixed min_score floor.","operationId":"SignalsController_getHighConviction","parameters":[{"name":"X-Request-ID","in":"header","description":"Optional client-supplied trace id. Echoed in response headers and error envelopes.","required":false,"schema":{"type":"string"}},{"name":"FilingIQ-Version","in":"header","description":"Pin the response shape to a specific FilingIQ-Version (YYYY-MM-DD). Documentation-only in v1; routing on this header lands with v2.","required":false,"schema":{"type":"string"}},{"name":"expand","required":false,"in":"query","description":"Comma-separated expansions: filer, company, latency.","schema":{"type":"string"}},{"name":"ticker","required":false,"in":"query","schema":{"type":"string"}},{"name":"starting_after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"example":25,"type":"number"}}],"responses":{"200":{"description":"High-conviction signal list."},"401":{"description":"Authentication failed."},"429":{"description":"Rate-limited."}},"security":[{"ApiKey":[]}],"summary":"List high-conviction signals (score >= 75)","tags":["Signals"]}},"/v1/signals/clusters":{"get":{"description":"Signals where 2 or more distinct insiders bought the same ticker within a 90-day window. Useful for surfacing coordinated executive accumulation.","operationId":"SignalsController_getClusters","parameters":[{"name":"X-Request-ID","in":"header","description":"Optional client-supplied trace id. Echoed in response headers and error envelopes.","required":false,"schema":{"type":"string"}},{"name":"FilingIQ-Version","in":"header","description":"Pin the response shape to a specific FilingIQ-Version (YYYY-MM-DD). Documentation-only in v1; routing on this header lands with v2.","required":false,"schema":{"type":"string"}},{"name":"expand","required":false,"in":"query","schema":{"type":"string"}},{"name":"ticker","required":false,"in":"query","schema":{"type":"string"}},{"name":"starting_after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"example":25,"type":"number"}}],"responses":{"200":{"description":"Clustered signal list."},"401":{"description":"Authentication failed."}},"security":[{"ApiKey":[]}],"summary":"List clustered insider buys","tags":["Signals"]}},"/v1/signals/congress":{"get":{"description":"Per-trade feed of disclosed politician transactions with conviction-pattern scoring.","operationId":"SignalsController_getCongress","parameters":[{"name":"X-Request-ID","in":"header","description":"Optional client-supplied trace id. Echoed in response headers and error envelopes.","required":false,"schema":{"type":"string"}},{"name":"FilingIQ-Version","in":"header","description":"Pin the response shape to a specific FilingIQ-Version (YYYY-MM-DD). Documentation-only in v1; routing on this header lands with v2.","required":false,"schema":{"type":"string"}},{"name":"ticker","required":false,"in":"query","schema":{"type":"string"}},{"name":"starting_after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"example":25,"type":"number"}}],"responses":{"200":{"description":"Congress trade list."},"401":{"description":"Authentication failed."}},"security":[{"ApiKey":[]}],"summary":"List congressional trades","tags":["Signals"]}},"/v1/signals/historical":{"get":{"description":"Unbounded lookback view. Requires at least one of: ticker filter, starting_after cursor, or a date range under 30 days. Otherwise returns 400 filter_required. since is silently clamped to the tier lookback window (professional: 1 year, enterprise: unlimited).","operationId":"SignalsController_getHistorical","parameters":[{"name":"X-Request-ID","in":"header","description":"Optional client-supplied trace id. Echoed in response headers and error envelopes.","required":false,"schema":{"type":"string"}},{"name":"FilingIQ-Version","in":"header","description":"Pin the response shape to a specific FilingIQ-Version (YYYY-MM-DD). Documentation-only in v1; routing on this header lands with v2.","required":false,"schema":{"type":"string"}},{"name":"expand","required":false,"in":"query","schema":{"type":"string"}},{"name":"since","required":false,"in":"query","description":"ISO 8601 timestamp or Unix seconds. Silently clamped to tier window.","schema":{"type":"string"}},{"name":"date_to","required":false,"in":"query","description":"ISO 8601 date.","schema":{"type":"string"}},{"name":"date_from","required":false,"in":"query","description":"ISO 8601 date (YYYY-MM-DD). Pair with date_to (range <= 30 days).","schema":{"type":"string"}},{"name":"min_score","required":false,"in":"query","schema":{"type":"number"}},{"name":"ticker","required":false,"in":"query","description":"Comma-separated tickers.","schema":{"type":"string"}},{"name":"starting_after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"example":25,"type":"number"}}],"responses":{"200":{"description":"Historical signal list."},"400":{"description":"filter_required - must supply ticker, cursor, or narrow date range."},"401":{"description":"Authentication failed."},"429":{"description":"Rate-limited or rows-quota exhausted."}},"security":[{"ApiKey":[]}],"summary":"Query historical signals (mandatory filter)","tags":["Signals"]}},"/v1/companies/{ticker}":{"get":{"description":"Returns the company resource for the given ticker symbol. Case-insensitive.","operationId":"CompaniesController_getByTicker","parameters":[{"name":"ticker","required":true,"in":"path","description":"Stock ticker, case-insensitive, e.g. NVDA.","schema":{"type":"string"}},{"name":"expand","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Company resource."},"404":{"description":"company_not_found."}},"security":[{"ApiKey":[]}],"summary":"Fetch a single company by ticker","tags":["Companies"]}},"/v1/companies/{ticker}/insiders":{"get":{"description":"Returns the deduplicated insider roster for the given ticker.","operationId":"CompaniesController_getInsiders","parameters":[{"name":"ticker","required":true,"in":"path","description":"Stock ticker.","schema":{"type":"string"}},{"name":"starting_after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"example":25,"type":"number"}}],"responses":{"200":{"description":"Insider list envelope."}},"security":[{"ApiKey":[]}],"summary":"List insiders for a company","tags":["Companies"]}},"/v1/companies/{ticker}/scores":{"get":{"description":"Per-trade composite score history for the given ticker.","operationId":"CompaniesController_getScores","parameters":[{"name":"ticker","required":true,"in":"path","description":"Stock ticker.","schema":{"type":"string"}},{"name":"starting_after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"example":25,"type":"number"}}],"responses":{"200":{"description":"Score history envelope."}},"security":[{"ApiKey":[]}],"summary":"List scoring history for a company","tags":["Companies"]}},"/v1/companies/{ticker}/signals":{"get":{"description":"Returns the most recent scored signals filtered to this ticker. Supports the same expand semantics as /v1/signals/latest (filer, company, latency).","operationId":"CompaniesController_getSignals","parameters":[{"name":"ticker","required":true,"in":"path","description":"Stock ticker.","schema":{"type":"string"}},{"name":"expand","required":false,"in":"query","schema":{"type":"string"}},{"name":"starting_after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"example":25,"type":"number"}}],"responses":{"200":{"description":"Signal list envelope."}},"security":[{"ApiKey":[]}],"summary":"List signals for a company","tags":["Companies"]}},"/v1/insiders/{identifier}":{"get":{"description":"Returns the insider record and their affiliated companies.","operationId":"InsidersController_getByIdentifier","parameters":[{"name":"identifier","required":true,"in":"path","description":"Internal insider identifier.","schema":{"type":"string"}},{"name":"expand","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Insider resource."},"404":{"description":"insider_not_found."}},"security":[{"ApiKey":[]}],"summary":"Fetch a single insider","tags":["Insiders"]}},"/v1/insiders/{identifier}/history":{"get":{"description":"Cursor-paginated trade history. since is silently clamped to the tier lookback window; the Warning header signals when clamping occurred.","operationId":"InsidersController_getHistory","parameters":[{"name":"identifier","required":true,"in":"path","description":"Internal insider identifier.","schema":{"type":"string"}},{"name":"expand","required":false,"in":"query","schema":{"type":"string"}},{"name":"since","required":false,"in":"query","description":"ISO 8601 or Unix seconds.","schema":{"type":"string"}},{"name":"starting_after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"example":25,"type":"number"}}],"responses":{"200":{"description":"Trade history envelope."},"400":{"description":"invalid_date_format."}},"security":[{"ApiKey":[]}],"summary":"List trade history for an insider","tags":["Insiders"]}},"/v1/insiders/{identifier}/performance":{"get":{"description":"Returns rolled-up performance statistics across the insider's disclosed trades.","operationId":"InsidersController_getPerformance","parameters":[{"name":"identifier","required":true,"in":"path","description":"Internal insider identifier.","schema":{"type":"string"}},{"name":"since","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Insider performance summary."}},"security":[{"ApiKey":[]}],"summary":"Aggregate performance for an insider","tags":["Insiders"]}},"/v1/alerts":{"post":{"description":"Creates a server-managed alert subscription with a score threshold and event-type filter.","operationId":"AlertsController_create","parameters":[{"name":"Idempotency-Key","in":"header","description":"Idempotency token, max 255 chars. Replays return the cached response byte-for-byte for 24h, scoped per API key. Required for safe retries of POST.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["score_threshold"],"properties":{"ticker":{"type":["string","null"],"description":"Optional ticker filter (uppercased)."},"score_threshold":{"type":"integer","minimum":0,"maximum":100,"description":"Required. 0-100."},"event_types":{"type":"array","items":{"type":"string"},"description":"Defaults to ['signal.created']."},"channel":{"type":"string","description":"Delivery channel, defaults to 'webhook'."},"channel_config":{"type":["object","null"],"additionalProperties":true,"description":"Channel-specific configuration."}}}}}},"responses":{"201":{"description":"Alert created."},"400":{"description":"invalid_score_threshold or other invalid field."}},"security":[{"ApiKey":[]}],"summary":"Create an alert","tags":["Alerts"]},"get":{"description":"Returns alerts owned by the calling API key.","operationId":"AlertsController_list","parameters":[{"name":"Idempotency-Key","in":"header","description":"Idempotency token, max 255 chars. Replays return the cached response byte-for-byte for 24h, scoped per API key. Required for safe retries of POST.","required":false,"schema":{"type":"string"}},{"name":"starting_after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"example":25,"type":"number"}}],"responses":{"200":{"description":"Alert list envelope."}},"security":[{"ApiKey":[]}],"summary":"List alerts","tags":["Alerts"]}},"/v1/alerts/{id}":{"delete":{"description":"Soft-revokes the alert. Idempotent (re-deletion returns 404).","operationId":"AlertsController_delete","parameters":[{"name":"Idempotency-Key","in":"header","description":"Idempotency token, max 255 chars. Replays return the cached response byte-for-byte for 24h, scoped per API key. Required for safe retries of POST.","required":false,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Alert id (with or without al_ prefix).","schema":{"type":"string"}}],"responses":{"204":{"description":"Alert deleted."},"404":{"description":"alert_not_found."}},"security":[{"ApiKey":[]}],"summary":"Delete an alert","tags":["Alerts"]}},"/v1/webhook_endpoints":{"post":{"description":"Creates a new webhook endpoint subscription. The plaintext signing secret is returned ONCE in the response and never again. Save it server-side immediately.","operationId":"WebhookEndpointsController_create","parameters":[{"name":"Idempotency-Key","in":"header","description":"Idempotency token (max 255 chars) for POST/PATCH/DELETE replays. Scoped per API key, 24h cache.","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event_types"],"properties":{"url":{"type":"string","description":"Required for generic/discord/slack. Omitted/empty for telegram."},"name":{"type":["string","null"]},"event_types":{"type":"array","items":{"type":"string"},"description":"e.g. ['signal.high_conviction']."},"ticker_filter":{"type":["array","null"],"items":{"type":"string"}},"min_score":{"type":["integer","null"],"minimum":0,"maximum":100},"min_score_overrides":{"type":["object","null"],"additionalProperties":{"type":"integer","minimum":0,"maximum":100},"description":"Optional per-event-type score override map, e.g. { \"signal.high_conviction\": 80 }."},"provider":{"type":"string","enum":["generic","discord","slack","telegram"],"description":"Routing target. Defaults to 'generic'."}}}}}},"responses":{"201":{"description":"Endpoint created; secret returned exactly once."},"400":{"description":"invalid_field."}},"security":[{"ApiKey":[]}],"summary":"Create a webhook endpoint","tags":["Webhooks"]},"get":{"description":"Returns endpoints owned by the calling API key.","operationId":"WebhookEndpointsController_list","parameters":[{"name":"Idempotency-Key","in":"header","description":"Idempotency token (max 255 chars) for POST/PATCH/DELETE replays. Scoped per API key, 24h cache.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Endpoint list."}},"security":[{"ApiKey":[]}],"summary":"List webhook endpoints","tags":["Webhooks"]}},"/v1/webhook_endpoints/{id}":{"get":{"operationId":"WebhookEndpointsController_getOne","parameters":[{"name":"Idempotency-Key","in":"header","description":"Idempotency token (max 255 chars) for POST/PATCH/DELETE replays. Scoped per API key, 24h cache.","required":false,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Endpoint id (with or without whe_ prefix).","schema":{"type":"string"}}],"responses":{"200":{"description":"Endpoint resource."},"404":{"description":"endpoint_not_found."}},"security":[{"ApiKey":[]}],"summary":"Fetch one webhook endpoint","tags":["Webhooks"]},"patch":{"description":"Partial update; only the fields supplied are changed.","operationId":"WebhookEndpointsController_update","parameters":[{"name":"Idempotency-Key","in":"header","description":"Idempotency token (max 255 chars) for POST/PATCH/DELETE replays. Scoped per API key, 24h cache.","required":false,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Endpoint id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Updated endpoint."}},"security":[{"ApiKey":[]}],"summary":"Update a webhook endpoint","tags":["Webhooks"]},"delete":{"operationId":"WebhookEndpointsController_remove","parameters":[{"name":"Idempotency-Key","in":"header","description":"Idempotency token (max 255 chars) for POST/PATCH/DELETE replays. Scoped per API key, 24h cache.","required":false,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Endpoint id.","schema":{"type":"string"}}],"responses":{"204":{"description":"Endpoint deleted."}},"security":[{"ApiKey":[]}],"summary":"Delete a webhook endpoint","tags":["Webhooks"]}},"/v1/webhook_endpoints/{id}/secrets/rotate":{"post":{"description":"Generates a new signing secret. The previous secret remains valid for a 24-hour overlap window so receivers can verify against either while migrating. The new plaintext secret is returned once.","operationId":"WebhookEndpointsController_rotateSecret","parameters":[{"name":"Idempotency-Key","in":"header","description":"Idempotency token (max 255 chars) for POST/PATCH/DELETE replays. Scoped per API key, 24h cache.","required":false,"schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Endpoint id.","schema":{"type":"string"}}],"responses":{"200":{"description":"New secret issued; previous secret remains valid for 24h."}},"security":[{"ApiKey":[]}],"summary":"Rotate the signing secret for an endpoint","tags":["Webhooks"]}},"/v1/webhook_endpoints/{id}/deliveries":{"get":{"description":"Returns the latest 100 dispatch attempts with status, latency, and response excerpt.","operationId":"WebhookDeliveriesController_list","parameters":[{"name":"id","required":true,"in":"path","description":"Endpoint id.","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"example":100,"type":"number"}}],"responses":{"200":{"description":"Delivery list envelope."}},"security":[{"ApiKey":[]}],"summary":"List recent deliveries for an endpoint","tags":["Webhooks"]}},"/v1/webhook_endpoints/{id}/deliveries/{deliveryId}/replay":{"post":{"description":"Enqueues a new delivery attempt for the same payload. Returns 202 immediately; check the deliveries log for the result.","operationId":"WebhookDeliveriesController_replay","parameters":[{"name":"id","required":true,"in":"path","description":"Endpoint id.","schema":{"type":"string"}},{"name":"deliveryId","required":true,"in":"path","description":"Delivery id (with or without whd_ prefix).","schema":{"type":"string"}}],"responses":{"202":{"description":"Replay queued."}},"security":[{"ApiKey":[]}],"summary":"Replay a single delivery","tags":["Webhooks"]}},"/v1/webhook_endpoints/{id}/deliveries/replay_failed":{"post":{"description":"Re-enqueues every distinct failed event since the supplied ISO 8601 timestamp. De-duped by event_id so an 8-attempt retry sequence only re-enqueues once.","operationId":"WebhookDeliveriesController_replayFailed","parameters":[{"name":"id","required":true,"in":"path","description":"Endpoint id.","schema":{"type":"string"}},{"name":"since","required":true,"in":"query","description":"ISO 8601 timestamp.","schema":{"type":"string"}}],"responses":{"202":{"description":"Replays queued."},"400":{"description":"invalid_field — since is required and must be ISO 8601."}},"security":[{"ApiKey":[]}],"summary":"Bulk replay failed deliveries since a timestamp","tags":["Webhooks"]}}},"info":{"title":"FilingIQ API","description":"Real-time insider trading signal infrastructure.\n\nCursor-paginated, idempotent, HMAC-signed webhooks.\nEvery payload carries a latency_ms field measuring the elapsed time from SEC publication to signal scoring.\n\nAuthentication: Bearer token. Issue keys at /settings/api on the FilingIQ dashboard.\nTiers: explorer, investor, alpha, professional, enterprise. API access requires professional or above.","version":"1.0","contact":{"name":"FilingIQ Support","url":"https://filingiq.io","email":"support@filingiq.io"},"license":{"name":"Proprietary","url":"https://filingiq.io/terms"}},"tags":[{"name":"Signals","description":"Scored insider trading signals (latest, high-conviction, clusters, historical)."},{"name":"Companies","description":"Per-ticker company metadata, insider rosters, scoring history."},{"name":"Insiders","description":"Per-insider trade history and aggregate performance."},{"name":"Alerts","description":"Server-managed alert preferences with score thresholds and event-type filters."},{"name":"Webhooks","description":"HMAC-signed event delivery to customer endpoints with replay support."}],"servers":[{"url":"https://api.filingiq.io","description":"Production"},{"url":"http://localhost:3001","description":"Local development"}],"components":{"securitySchemes":{"ApiKey":{"scheme":"bearer","bearerFormat":"fiq_live_...","type":"http","description":"API key issued from the FilingIQ dashboard /settings/api. Prefix `fiq_live_` for production, `fiq_test_` for sandbox."}},"schemas":{}}}