{"openapi":"3.1.0","info":{"title":"InvestWhen Finance Data API","version":"v1","summary":"Read-only, factual U.S. equity data: SEC filings, insider transactions (Form 4), 13F institutional holdings and earnings.","description":"Precomputed, read-only equity facts. No endpoint enqueues work or calls a language model, so throughput is bounded by your plan's rate limit and nothing else.\n\n**Rate limits by plan** — free 10/min and 200/day, pages up to 10, SEC facts only (no written summaries), signal 60/min and 5000/day, pages up to 50, insider 180/min and 50000/day, pages up to 100, founders 300/min and 200000/day, pages up to 200. Live figures for YOUR key: `GET /api/v1/meta`. Every response carries `X-RateLimit-*` headers.\n\n**Written summaries** are our own factual prose and are included from the Signal plan up; the public-domain SEC facts (numbers, dates, filings) are returned on every plan, including free.\n\n**Not advice.** Responses contain no recommendations, price targets or ratings, by design.\n\n**Reuse.** The SEC facts are public domain and need no permission. The written summaries and analysis are ours: reuse them with the credit in each response's `attribution` field visible and linked. Full terms: https://investwhen.com/terms#content","termsOfService":"https://investwhen.com/terms","license":{"name":"SEC EDGAR public domain + InvestWhen analysis (reuse with credit)","url":"https://investwhen.com/terms#content"},"contact":{"name":"InvestWhen","url":"https://investwhen.com/developers"}},"servers":[{"url":"https://investwhen.com","description":"Production"}],"externalDocs":{"description":"Developer portal — plans, keys, examples","url":"https://investwhen.com/developers"},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer iw_live_…` — mint a key at /developers."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative to the bearer header. Keys are accepted in HEADERS ONLY — never in the query string, which would leak them into access logs and Referer headers."}},"schemas":{"Error":{"type":"object","required":["ok","error","detail"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string","description":"Stable machine-readable code.","enum":["invalid_api_key","account_unavailable","subscription_suspended","api_not_available_on_plan","rate_limited_minute","rate_limited_day","service_busy"]},"detail":{"type":"string"},"license":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Missing or unknown key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"The account's subscription has lapsed — renew to restore access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The account is inactive, or its plan has no API access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Over the per-minute or per-day limit. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Busy":{"description":"Service-wide breaker tripped; retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"tags":[{"name":"meta","description":"Your plan, limits and current usage."},{"name":"finance","description":"Factual U.S. equity data."}],"paths":{"/api/v1/meta":{"get":{"tags":["meta"],"summary":"Your plan, limits and usage","description":"What this key may do and how much of it is left — the endpoint to call first, and the only one that reports max_page_size for your plan.","operationId":"your_plan,_limits_and_usage","parameters":[],"responses":{"200":{"description":"Plan, limits and usage for the calling key.","headers":{"X-RateLimit-Limit-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["ok","api_version","as_of","license","attribution","data"],"properties":{"ok":{"type":"boolean","const":true},"api_version":{"type":"string","example":"v1"},"as_of":{"type":"string","format":"date-time","description":"When this response was assembled (UTC, ISO 8601)."},"license":{"type":"string","description":"Data licence + the information-only disclaimer that travels with every response."},"attribution":{"type":"string","description":"The credit to display when you reuse the written analysis. Reuse is permitted with this credit visible and linked.","example":"Analysis by InvestWhen (https://investwhen.com)"},"count":{"type":"integer","description":"Rows in `data`."},"data":{"type":"array","description":"Plan, limits and usage for the calling key.","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Busy"}}}},"/api/v1/finance/reports":{"get":{"tags":["finance"],"summary":"Company reports","description":"Our factual per-company report. Omit `ticker` for the most recent; pass one for that company only.","operationId":"company_reports","parameters":[{"name":"limit","in":"query","required":false,"description":"Rows to return. Clamped to your plan's max_page_size (see GET /api/v1/meta).","schema":{"type":"integer","minimum":1,"default":20}},{"name":"ticker","in":"query","required":false,"description":"Restrict to one ticker, e.g. AAPL.","schema":{"type":"string","maxLength":12,"example":"AAPL"}}],"responses":{"200":{"description":"Company reports.","headers":{"X-RateLimit-Limit-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["ok","api_version","as_of","license","attribution","data"],"properties":{"ok":{"type":"boolean","const":true},"api_version":{"type":"string","example":"v1"},"as_of":{"type":"string","format":"date-time","description":"When this response was assembled (UTC, ISO 8601)."},"license":{"type":"string","description":"Data licence + the information-only disclaimer that travels with every response."},"attribution":{"type":"string","description":"The credit to display when you reuse the written analysis. Reuse is permitted with this credit visible and linked.","example":"Analysis by InvestWhen (https://investwhen.com)"},"count":{"type":"integer","description":"Rows in `data`."},"data":{"type":"array","description":"Company reports.","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Busy"}}}},"/api/v1/finance/insiders":{"get":{"tags":["finance"],"summary":"Insider transactions (Form 4)","description":"Insider buying and selling from SEC Form 4 filings, aggregated per company. Omit `ticker` for a cross-company overview.","operationId":"insider_transactions_form_4","parameters":[{"name":"limit","in":"query","required":false,"description":"Rows to return. Clamped to your plan's max_page_size (see GET /api/v1/meta).","schema":{"type":"integer","minimum":1,"default":20}},{"name":"ticker","in":"query","required":false,"description":"Restrict to one ticker, e.g. AAPL.","schema":{"type":"string","maxLength":12,"example":"AAPL"}}],"responses":{"200":{"description":"Insider-activity summaries.","headers":{"X-RateLimit-Limit-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["ok","api_version","as_of","license","attribution","data"],"properties":{"ok":{"type":"boolean","const":true},"api_version":{"type":"string","example":"v1"},"as_of":{"type":"string","format":"date-time","description":"When this response was assembled (UTC, ISO 8601)."},"license":{"type":"string","description":"Data licence + the information-only disclaimer that travels with every response."},"attribution":{"type":"string","description":"The credit to display when you reuse the written analysis. Reuse is permitted with this credit visible and linked.","example":"Analysis by InvestWhen (https://investwhen.com)"},"count":{"type":"integer","description":"Rows in `data`."},"data":{"type":"array","description":"Insider-activity summaries.","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Busy"}}}},"/api/v1/finance/whales":{"get":{"tags":["finance"],"summary":"13F institutional holdings","description":"Institutional filers and their largest disclosed positions, from 13F filings. Filter to one filer with `cik`.","operationId":"13f_institutional_holdings","parameters":[{"name":"limit","in":"query","required":false,"description":"Rows to return. Clamped to your plan's max_page_size (see GET /api/v1/meta).","schema":{"type":"integer","minimum":1,"default":20}},{"name":"cik","in":"query","required":false,"description":"Restrict to one filer by SEC CIK.","schema":{"type":"string","maxLength":20}}],"responses":{"200":{"description":"Filers and their top holdings.","headers":{"X-RateLimit-Limit-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["ok","api_version","as_of","license","attribution","data"],"properties":{"ok":{"type":"boolean","const":true},"api_version":{"type":"string","example":"v1"},"as_of":{"type":"string","format":"date-time","description":"When this response was assembled (UTC, ISO 8601)."},"license":{"type":"string","description":"Data licence + the information-only disclaimer that travels with every response."},"attribution":{"type":"string","description":"The credit to display when you reuse the written analysis. Reuse is permitted with this credit visible and linked.","example":"Analysis by InvestWhen (https://investwhen.com)"},"count":{"type":"integer","description":"Rows in `data`."},"data":{"type":"array","description":"Filers and their top holdings.","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Busy"}}}},"/api/v1/finance/earnings":{"get":{"tags":["finance"],"summary":"Earnings recaps","description":"Filed earnings releases with our factual recap where one exists.","operationId":"earnings_recaps","parameters":[{"name":"limit","in":"query","required":false,"description":"Rows to return. Clamped to your plan's max_page_size (see GET /api/v1/meta).","schema":{"type":"integer","minimum":1,"default":20}},{"name":"ticker","in":"query","required":false,"description":"Restrict to one ticker, e.g. AAPL.","schema":{"type":"string","maxLength":12,"example":"AAPL"}}],"responses":{"200":{"description":"Earnings releases.","headers":{"X-RateLimit-Limit-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["ok","api_version","as_of","license","attribution","data"],"properties":{"ok":{"type":"boolean","const":true},"api_version":{"type":"string","example":"v1"},"as_of":{"type":"string","format":"date-time","description":"When this response was assembled (UTC, ISO 8601)."},"license":{"type":"string","description":"Data licence + the information-only disclaimer that travels with every response."},"attribution":{"type":"string","description":"The credit to display when you reuse the written analysis. Reuse is permitted with this credit visible and linked.","example":"Analysis by InvestWhen (https://investwhen.com)"},"count":{"type":"integer","description":"Rows in `data`."},"data":{"type":"array","description":"Earnings releases.","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Busy"}}}},"/api/v1/finance/filings":{"get":{"tags":["finance"],"summary":"Recent SEC filings","description":"Recently filed SEC documents with a link to the primary document and our factual summary where one exists.","operationId":"recent_sec_filings","parameters":[{"name":"limit","in":"query","required":false,"description":"Rows to return. Clamped to your plan's max_page_size (see GET /api/v1/meta).","schema":{"type":"integer","minimum":1,"default":20}},{"name":"ticker","in":"query","required":false,"description":"Restrict to one ticker, e.g. AAPL.","schema":{"type":"string","maxLength":12,"example":"AAPL"}}],"responses":{"200":{"description":"SEC filings.","headers":{"X-RateLimit-Limit-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Minute":{"schema":{"type":"integer"}},"X-RateLimit-Limit-Day":{"schema":{"type":"integer"}},"X-RateLimit-Remaining-Day":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["ok","api_version","as_of","license","attribution","data"],"properties":{"ok":{"type":"boolean","const":true},"api_version":{"type":"string","example":"v1"},"as_of":{"type":"string","format":"date-time","description":"When this response was assembled (UTC, ISO 8601)."},"license":{"type":"string","description":"Data licence + the information-only disclaimer that travels with every response."},"attribution":{"type":"string","description":"The credit to display when you reuse the written analysis. Reuse is permitted with this credit visible and linked.","example":"Analysis by InvestWhen (https://investwhen.com)"},"count":{"type":"integer","description":"Rows in `data`."},"data":{"type":"array","description":"SEC filings.","items":{"type":"object","additionalProperties":true}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Busy"}}}}}}