{"openapi":"3.1.0","info":{"title":"SEC API","version":"1.0.0","description":"Normalized SEC EDGAR data. An independent service, not affiliated with the SEC. Quotas are per account across keys. Offset pagination covers the current cached snapshot."},"servers":[{"url":"https://sec-api.dev"}],"paths":{"/api/v1/companies":{"get":{"summary":"Search listed companies","security":[{"ApiKey":[]}],"parameters":[{"name":"query","in":"query","required":true,"description":"Ticker or company-name substring.","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"limit","in":"query","required":false,"description":"Maximum records returned. Responses also obey a 900 KB data budget.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Source-backed SEC data; inspect meta.stale and fetchedAt.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanySummary"}},"meta":{"$ref":"#/components/schemas/Meta"},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"SEC dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minute or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid or oversized SEC response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary upstream or infrastructure failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/companies/{cik}":{"get":{"summary":"Retrieve company metadata","security":[{"ApiKey":[]}],"parameters":[{"name":"cik","in":"path","required":true,"description":"SEC Central Index Key; accepts 1 to 10 digits.","schema":{"type":"string","pattern":"^[0-9]{1,10}$"}}],"responses":{"200":{"description":"Source-backed SEC data; inspect meta.stale and fetchedAt.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Company"},"meta":{"$ref":"#/components/schemas/Meta"},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"SEC dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minute or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid or oversized SEC response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary upstream or infrastructure failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/filings":{"get":{"summary":"Retrieve recent company filings","description":"Covers the recent submissions array only. meta.historyCoverage is recent. Older historical submission files are not included.","security":[{"ApiKey":[]}],"parameters":[{"name":"cik","in":"query","required":true,"description":"SEC Central Index Key; accepts 1 to 10 digits.","schema":{"type":"string","pattern":"^[0-9]{1,10}$"}},{"name":"form","in":"query","required":false,"description":"Exact SEC form; e.g. 10-K, 10-Q, 8-K or 10-K/A.","schema":{"type":"string","maxLength":24}},{"name":"limit","in":"query","required":false,"description":"Maximum records returned. Responses also obey a 900 KB data budget.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","required":false,"description":"Zero-based offset in the current SEC snapshot. Dataset updates may shift offsets; use fetchedAt to detect refreshes.","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"Source-backed SEC data; inspect meta.stale and fetchedAt.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Filing"}},"meta":{"$ref":"#/components/schemas/Meta"},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"SEC dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minute or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid or oversized SEC response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary upstream or infrastructure failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/facts/{cik}":{"get":{"summary":"Retrieve individual XBRL observations","description":"Observations preserve units, filing accession numbers and restatements. No implicit latest-value selection. Standard entity-wide taxonomy facts only.","security":[{"ApiKey":[]}],"parameters":[{"name":"cik","in":"path","required":true,"description":"SEC Central Index Key; accepts 1 to 10 digits.","schema":{"type":"string","pattern":"^[0-9]{1,10}$"}},{"name":"concept","in":"query","required":false,"description":"Exact standard taxonomy concept, e.g. Assets.","schema":{"type":"string","maxLength":150}},{"name":"taxonomy","in":"query","required":false,"description":"Exact taxonomy, e.g. us-gaap.","schema":{"type":"string","maxLength":150}},{"name":"unit","in":"query","required":false,"description":"Exact unit, e.g. USD.","schema":{"type":"string","maxLength":150}},{"name":"limit","in":"query","required":false,"description":"Maximum records returned. Responses also obey a 900 KB data budget.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","required":false,"description":"Zero-based offset in the current SEC snapshot. Dataset updates may shift offsets; use fetchedAt to detect refreshes.","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}}],"responses":{"200":{"description":"Source-backed SEC data; inspect meta.stale and fetchedAt.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Fact"}},"meta":{"$ref":"#/components/schemas/Meta"},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"SEC dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minute or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid or oversized SEC response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary upstream or infrastructure failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/playground":{"get":{"summary":"Run a bounded public demonstration","description":"20 requests per hour per visitor IP. Filings are limited to three 10-K records; facts to ten USD Assets observations.","security":[],"parameters":[{"name":"endpoint","in":"query","required":false,"description":"Dataset to demonstrate.","schema":{"type":"string","enum":["companies","company","filings","facts"],"default":"filings"}},{"name":"ticker","in":"query","required":false,"description":"Supported demo company.","schema":{"type":"string","enum":["AAPL","MSFT","NVDA"],"default":"AAPL"}}],"responses":{"200":{"description":"Source-backed SEC data; inspect meta.stale and fetchedAt.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{},"meta":{"$ref":"#/components/schemas/Meta"},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"SEC dataset not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Minute or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid or oversized SEC response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary upstream or infrastructure failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"Create a key in your dashboard. Send Authorization: Bearer sk_sec_…"}},"schemas":{"Meta":{"type":"object","required":["requestId","source","fetchedAt","stale"],"properties":{"requestId":{"type":"string","format":"uuid"},"source":{"type":"string","format":"uri"},"fetchedAt":{"type":"string","format":"date-time"},"stale":{"type":"boolean"},"historyCoverage":{"type":"string","enum":["recent"]}}},"Pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"nextOffset":{"type":["integer","null"]},"total":{"type":"integer"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"retryAfter":{"type":"integer"}}}}},"CompanySummary":{"type":"object","properties":{"cik":{"type":"string"},"ticker":{"type":"string"},"name":{"type":"string"}}},"Company":{"type":"object","properties":{"cik":{"type":"string"},"name":{"type":"string"},"tickers":{"type":"array","items":{"type":"string"}},"exchanges":{"type":"array","items":{"type":"string"}},"sic":{"type":["string","null"]},"sicDescription":{"type":["string","null"]},"fiscalYearEnd":{"type":["string","null"]},"website":{"type":["string","null"]}}},"Filing":{"type":"object","properties":{"cik":{"type":"string"},"accessionNumber":{"type":"string"},"form":{"type":"string"},"filingDate":{"type":"string","format":"date"},"reportDate":{"type":["string","null"]},"acceptedAt":{"type":["string","null"]},"primaryDocument":{"type":["string","null"]},"documentUrl":{"type":["string","null"]},"isXbrl":{"type":"boolean"},"isInlineXbrl":{"type":"boolean"}}},"Fact":{"type":"object","properties":{"taxonomy":{"type":"string"},"concept":{"type":"string"},"label":{"type":["string","null"]},"description":{"type":["string","null"]},"unit":{"type":"string"},"value":{"type":"number"},"start":{"type":"string"},"end":{"type":"string"},"filed":{"type":"string"},"accessionNumber":{"type":"string"},"form":{"type":"string"},"fiscalYear":{"type":"integer"},"fiscalPeriod":{"type":"string"},"frame":{"type":"string"}}}}}}