{ "openapi": "3.1.0", "info": { "title": "filings.tools: SEC filings API", "version": "1.0.0", "summary": "List 10-K, 10-Q and 8-K filings by ticker, read parsed sections and XBRL facts.", "description": "Look up a company by ticker or CIK, list its recent filings, then read a filing as parsed sections in JSON or Markdown, read its XBRL facts, or compare it with the preceding filing. Every company in the SEC ticker list is covered. Every answer links to the original document on sec.gov.\n\nStart with `GET /api/v1/filings?ticker=AAPL`. Use an `id` from the answer in the other routes.\n\nSource documents are public domain SEC filings. Check important values against the original on sec.gov.\n\nExample values in this document are illustrations. The ids, accession numbers and figures in the examples are not real filings.\n\n## Limits and plans\n\nFree service is also subject to shared daily capacity. If it is exhausted, retry after the time in Retry-After. Paid plan allowances remain separate.\n\nA request with no key works. It is the anonymous tier. A key raises the ceiling.\n\n- No key: 25 calls a day per IP address. The count resets at 00:00 UTC.\n- Free key: 200 calls a day. Get one with your email at https://filings.tools/billing/free. Free use is for one person: your own projects or your studies. Production, team and commercial use need a paid plan.\n- Starter: $19 a month for 10,000 calls a day.\n- Pro: $49 a month for 50,000 calls a day, with bulk facts (?all=1).\n- Business: $199 a month for 250,000 calls a day, with bulk facts (?all=1).\n\nEvery answer from a counted route carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds), and `X-RateLimit-Unit` (calls). Over the limit, the route answers 429 with a `pricing` link and, without a key, a `free_key` link.\nPlans and prices: https://filings.tools/pricing.\nTerms: https://filings.tools/terms. Privacy: https://filings.tools/privacy. Contact: hello@darkvectorcognition.ai.", "termsOfService": "https://filings.tools/terms", "contact": { "name": "Dark Vector Cognition", "email": "hello@darkvectorcognition.ai", "url": "https://filings.tools/docs" } }, "servers": [ { "url": "https://filings.tools", "description": "Production" } ], "externalDocs": { "description": "filings.tools: SEC filings API guide", "url": "https://filings.tools/docs" }, "security": [ {}, { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "tags": [ { "name": "Filings", "description": "Lookup, sections, facts and comparison. Counted in calls." }, { "name": "Account", "description": "Read your own allowance. Uses none of it." } ], "paths": { "/api/v1/filings": { "get": { "operationId": "listFilings", "summary": "List recent filings of a company", "description": "Returns the company profile and its recent filings with ids. Forms: 10-K, 10-Q, 8-K, 10-K/A, 10-Q/A, 20-F, 40-F. Any company in the SEC ticker list works, by ticker (EDGAR spelling, so BRK-B; BRK.B is accepted) or by CIK.\n\nSend `ticker` or `cik`. A CIK also works in `ticker`. One call uses one unit of the allowance.", "tags": [ "Filings" ], "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "A ticker such as NVDA. A CIK also works here. Send `ticker` or `cik`.", "schema": { "type": "string", "examples": [ "NVDA" ] } }, { "name": "cik", "in": "query", "required": false, "description": "A CIK, a number of at most 10 digits. A ticker here is a 400 `invalid_cik`.", "schema": { "type": "string", "pattern": "^[0-9]{1,10}$", "examples": [ "1045810" ] } }, { "name": "form", "in": "query", "required": false, "description": "Only filings of this form.", "schema": { "type": "string", "examples": [ "10-K" ] } }, { "name": "limit", "in": "query", "required": false, "description": "The most filings to return. At most 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "The company and its filings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilingList" }, "example": { "company": { "cik": 1045810, "ticker": "NVDA", "name": "NVIDIA CORP", "sic": "3674", "sicDescription": "Semiconductors & Related Devices", "fiscalYearEnd": "0126" }, "filings": [ { "id": "1045810-000104581026000021", "form": "10-K", "filingDate": "2026-02-25", "reportDate": "2026-01-25", "accession": "0001045810-26-000021", "sourceUrl": "https://www.sec.gov/Archives/edgar/data/1045810/000104581026000021/nvda-20260125.htm", "pageUrl": "https://filings.tools/nvda/10-k/2026-01-25", "sectionsUrl": "https://filings.tools/api/v1/filings/1045810-000104581026000021/sections" } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-RateLimit-Unit": { "$ref": "#/components/headers/XRateLimitUnit" }, "X-Caller": { "$ref": "#/components/headers/XCaller" } } }, "400": { "description": "Neither `ticker` nor `cik` was sent (`missing_ticker`), or `cik` holds a ticker (`invalid_cik`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_ticker": { "value": { "error": "missing_ticker", "message": "Pass ?ticker=NVDA or ?cik=1045810" } }, "invalid_cik": { "value": { "error": "invalid_cik", "message": "?cik= takes a CIK, a number such as 1045810. For a ticker use ?ticker=NVDA.", "cik": "NVDA" } } } } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "402": { "$ref": "#/components/responses/TrialEnded" }, "404": { "description": "The ticker or CIK is not in the SEC ticker list. The body has close matches and a link to the SEC company search.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnknownCompany" }, "example": { "error": "unknown_ticker", "ticker": "NVDAA", "message": "No company in the SEC's ticker list has the ticker NVDAA. Close matches: NVDA.", "search": "https://www.sec.gov/search-filings", "suggestions": [ { "ticker": "NVDA", "cik": 1045810, "name": "NVIDIA CORP" } ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "EDGAR is busy (`edgar_busy`: the SEC allows ten requests a second, so this one waits its turn) or did not answer (`edgar_unavailable`). Also the gate answers 503 `billing_store_unavailable` when it cannot verify a key. Retry after the seconds in `Retry-After`.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unavailable" }, "example": { "error": "edgar_busy", "message": "Too many filings are being fetched from the SEC right now. The SEC allows ten requests a second, so this one waits its turn. Try again shortly.", "retryAfter": 3 } } } } } } }, "/api/v1/filings/{id}/sections": { "get": { "operationId": "getFilingSections", "summary": "Read a filing as parsed sections", "description": "The filing split into its items, as JSON or as one Markdown document. Use `section` to get one item. Section ids look like `item-1a`.\n\nSend `format=md` or `Accept: text/markdown` for Markdown.\n\nFor direct REST scripts, send a free API key in the `x-api-key` header. Downloads without a key may require browser verification. MCP does not require a browser check.\n\nThe parse is kept on the server by accession, so a repeat call is faster. The answer is never stored by a shared cache, because it carries your allowance.", "tags": [ "Filings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A filing id from GET /api/v1/filings: the CIK, a dash, and the accession number without dashes.", "schema": { "type": "string", "pattern": "^[0-9]+-[0-9]{18}$", "examples": [ "1045810-000104581026000021" ] } }, { "name": "section", "in": "query", "required": false, "description": "Only this section id, for example item-1a. An id that does not exist returns an empty `sections` list.", "schema": { "type": "string", "examples": [ "item-1a" ] } }, { "name": "format", "in": "query", "required": false, "description": "`md` returns one Markdown document.", "schema": { "type": "string", "enum": [ "md" ] } } ], "responses": { "200": { "description": "The sections. `X-Filings-Parse` says whether the parse came from the server cache or was run for this call.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-RateLimit-Unit": { "$ref": "#/components/headers/XRateLimitUnit" }, "X-Caller": { "$ref": "#/components/headers/XCaller" }, "X-Filings-Parse": { "description": "cache or parsed.", "schema": { "type": "string", "enum": [ "cache", "parsed" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParsedFiling" }, "example": { "id": "1045810-000104581026000021", "product": "filings", "title": "NVIDIA CORP 10-K 2026-01-25", "sourceUrl": "https://www.sec.gov/Archives/edgar/data/1045810/000104581026000021/nvda-20260125.htm", "sections": [ { "id": "item-1a", "title": "Item 1A. Risk Factors", "markdown": "Risks related to our industry and markets...", "chars": 44 } ], "topics": [], "parserVersion": "1", "meta": { "ticker": "NVDA", "cik": 1045810, "form": "10-K", "accession": "0001045810-26-000021", "filingDate": "2026-02-25", "reportDate": "2026-01-25", "slug": "nvda-10-k-2026-01-25" } } }, "text/markdown": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "402": { "$ref": "#/components/responses/TrialEnded" }, "404": { "description": "No filing has this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not_found", "message": "No filing has this id.", "id": "1045810-000104581026000021" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "EDGAR is busy (`edgar_busy`: the SEC allows ten requests a second, so this one waits its turn) or did not answer (`edgar_unavailable`). Also the gate answers 503 `billing_store_unavailable` when it cannot verify a key. Retry after the seconds in `Retry-After`.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unavailable" }, "example": { "error": "edgar_busy", "message": "Too many filings are being fetched from the SEC right now. The SEC allows ten requests a second, so this one waits its turn. Try again shortly.", "retryAfter": 3 } } } } } } }, "/api/v1/filings/{id}/facts": { "get": { "operationId": "getFilingFacts", "summary": "Read XBRL facts of a filing", "description": "Ten reported concepts: revenue, net income, diluted EPS, total assets, cash, long-term debt, shares outstanding, operating income, capex and operating cash flow. Each value has its unit and period.\n\nWithout `all` the facts are the ones tagged to this filing. `all=1` returns every reported period for the company and is part of the Pro and Business plans. Other callers get 403 `plan_required`.", "tags": [ "Filings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A filing id from GET /api/v1/filings: the CIK, a dash, and the accession number without dashes.", "schema": { "type": "string", "pattern": "^[0-9]+-[0-9]{18}$", "examples": [ "1045810-000104581026000021" ] } }, { "name": "all", "in": "query", "required": false, "description": "Any value returns every reported period. Pro and Business plans only.", "schema": { "type": "string", "examples": [ "1" ] } } ], "responses": { "200": { "description": "The facts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactsResult" }, "example": { "company": { "cik": 1045810, "ticker": "NVDA", "name": "NVIDIA CORP" }, "filing": { "id": "1045810-000104581026000021", "form": "10-K", "accession": "0001045810-26-000021", "filingDate": "2026-02-25", "reportDate": "2026-01-25", "sourceUrl": "https://www.sec.gov/Archives/edgar/data/1045810/000104581026000021/nvda-20260125.htm" }, "facts": [ { "concept": "Revenues", "friendly": "revenue", "value": 130497000000, "unit": "USD", "start": "2025-01-27", "end": "2026-01-25", "fy": 2026, "fp": "FY", "form": "10-K", "filed": "2026-02-25", "accession": "0001045810-26-000021" } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-RateLimit-Unit": { "$ref": "#/components/headers/XRateLimitUnit" }, "X-Caller": { "$ref": "#/components/headers/XCaller" } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "402": { "$ref": "#/components/responses/TrialEnded" }, "403": { "description": "`all=1` needs a Pro or Business plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "plan_required", "message": "Bulk facts (?all=1, every reported period) are part of the Pro and Business plans. Without ?all=1 this route returns the facts for this filing.", "pricing": "https://filings.tools/pricing" } } } }, "404": { "description": "No filing has this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not_found", "message": "", "id": "1045810-000104581026000021" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "EDGAR is busy (`edgar_busy`: the SEC allows ten requests a second, so this one waits its turn) or did not answer (`edgar_unavailable`). Also the gate answers 503 `billing_store_unavailable` when it cannot verify a key. Retry after the seconds in `Retry-After`.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unavailable" }, "example": { "error": "edgar_busy", "message": "Too many filings are being fetched from the SEC right now. The SEC allows ten requests a second, so this one waits its turn. Try again shortly.", "retryAfter": 3 } } } } } } }, "/api/v1/filings/{id}/diff": { "get": { "operationId": "compareFiling", "summary": "Compare a filing with the preceding one", "description": "Compares the filing with the preceding available filing of the same form. The answer has counts of added, removed and changed sentences, and limited samples. It is not a full redline.\n\nThe earliest filing of a form has nothing to compare against. That is a 200 with `comparable: false` and a reason, not an error.\n\nFor direct REST scripts, send a free API key in the `x-api-key` header. Downloads without a key may require browser verification. MCP does not require a browser check.", "tags": [ "Filings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A filing id from GET /api/v1/filings: the CIK, a dash, and the accession number without dashes.", "schema": { "type": "string", "pattern": "^[0-9]+-[0-9]{18}$", "examples": [ "1045810-000104581026000021" ] } } ], "responses": { "200": { "description": "A comparison, or a reason there is none.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Comparison" }, { "$ref": "#/components/schemas/NotComparable" } ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-RateLimit-Unit": { "$ref": "#/components/headers/XRateLimitUnit" }, "X-Caller": { "$ref": "#/components/headers/XCaller" } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "402": { "$ref": "#/components/responses/TrialEnded" }, "404": { "description": "No filing has this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not_found", "message": "No filing with id 1045810-000104581026000021." } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "EDGAR is busy (`edgar_busy`: the SEC allows ten requests a second, so this one waits its turn) or did not answer (`edgar_unavailable`). Also the gate answers 503 `billing_store_unavailable` when it cannot verify a key. Retry after the seconds in `Retry-After`.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unavailable" }, "example": { "error": "edgar_busy", "message": "Too many filings are being fetched from the SEC right now. The SEC allows ten requests a second, so this one waits its turn. Try again shortly.", "retryAfter": 3 } } } } } } }, "/api/v1/filings/{id}/tables": { "get": { "operationId": "getFilingTables", "summary": "Export the tables of a filing", "description": "Every table in a filing or one section, as CSV (the default) or JSON. Split figures are joined and spacer columns are dropped, so columns line up in a spreadsheet. Values are copied as filed, never recomputed.\n\nNeeds a key of any filings plan. A request with no key answers 401 and a key that is not a subscription answers 403. Both use none of your allowance. A successful export is one call.", "tags": [ "Filings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "A filing id from GET /api/v1/filings: the CIK, a dash, and the accession number without dashes.", "schema": { "type": "string", "pattern": "^[0-9]+-[0-9]{18}$", "examples": [ "1045810-000104581026000021" ] } }, { "name": "section", "in": "query", "required": false, "description": "Only the tables of this section id.", "schema": { "type": "string", "examples": [ "item-8" ] } }, { "name": "format", "in": "query", "required": false, "description": "`json` returns rows as JSON. Anything else returns CSV.", "schema": { "type": "string", "enum": [ "csv", "json" ], "default": "csv" } } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "The tables.", "content": { "text/csv": { "schema": { "type": "string" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FilingTables" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-RateLimit-Unit": { "$ref": "#/components/headers/XRateLimitUnit" }, "X-Caller": { "$ref": "#/components/headers/XCaller" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/TrialEnded" }, "403": { "description": "The key is not a filings subscription (`not_a_subscriber`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not_a_subscriber", "message": "That key does not belong to an active filings.tools subscription.", "pricing": "https://filings.tools/pricing" } } } }, "404": { "description": "No filing with this id (`not_found`), no such section (`no_section`) or no tables (`no_tables`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "no_tables", "message": "This filing has no tables.", "pricing": "https://filings.tools/pricing" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "EDGAR is busy (`edgar_busy`: the SEC allows ten requests a second, so this one waits its turn) or did not answer (`edgar_unavailable`). Also the gate answers 503 `billing_store_unavailable` when it cannot verify a key. Retry after the seconds in `Retry-After`.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Unavailable" }, "example": { "error": "edgar_busy", "message": "Too many filings are being fetched from the SEC right now. The SEC allows ten requests a second, so this one waits its turn. Try again shortly.", "retryAfter": 3 } } } } } } }, "/api/v1/me": { "get": { "operationId": "getStanding", "summary": "Read your own allowance", "description": "Returns whether you call anonymously or with a key, your daily ceiling, what is left and when it resets. Reading it uses none of your allowance.", "tags": [ "Account" ], "responses": { "200": { "description": "Your standing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Standing" }, "example": { "product": "filings", "caller": "anon", "limitKind": "calls_day", "unit": "calls", "limit": 25, "remaining": 20, "used": 5, "reset": 1790000000, "resetIso": "2026-10-09T00:00:00.000Z", "backend": "upstash", "persistent": true, "unavailable": false, "recover": "https://filings.tools/billing/regenerate", "pricing": "https://filings.tools/pricing", "free_key": "https://filings.tools/billing/free" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your filings.tools key. Optional. Without it the request is anonymous. Metered routes reject an unknown or revoked key with 401. Remove the header to use the anonymous tier." }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "The same key, sent as `Authorization: Bearer YOUR_KEY`. Use one of the two headers, not both." } }, "headers": { "XRateLimitLimit": { "description": "The ceiling that applies to this caller, in calls.", "schema": { "type": "integer", "examples": [ 25 ] } }, "XRateLimitRemaining": { "description": "Calls left in the current period.", "schema": { "type": "integer", "examples": [ 24 ] } }, "XRateLimitReset": { "description": "When the count resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1790000000 ] } }, "XRateLimitUnit": { "description": "The unit of the three headers above: calls or pages.", "schema": { "type": "string", "enum": [ "calls", "pages" ] } }, "XCaller": { "description": "anon when the request had no valid key, key when it had one.", "schema": { "type": "string", "enum": [ "anon", "key" ] } }, "RetryAfter": { "description": "Seconds to wait before the next try.", "schema": { "type": "integer", "examples": [ 5 ] } } }, "schemas": { "Error": { "type": "object", "description": "The body of every error answer. `error` is a stable code. `message` is for a person.", "required": [ "error" ], "properties": { "error": { "type": "string", "examples": [ "missing_file" ] }, "message": { "type": "string" } }, "additionalProperties": true }, "RateLimitError": { "type": "object", "description": "The body of a 413 or 429 from the gate.", "required": [ "error", "message", "pricing", "recover" ], "properties": { "error": { "type": "string", "enum": [ "rate_limited", "file_too_long" ] }, "message": { "type": "string", "examples": [ "Daily limit of 25 pages reached. It resets at 00:00 UTC." ] }, "free_key": { "type": "string", "format": "uri", "description": "Only for a caller without a key: where to get a free key.", "examples": [ "https://filings.tools/billing/free" ] }, "pricing": { "type": "string", "format": "uri", "examples": [ "https://filings.tools/pricing" ] }, "recover": { "type": "string", "format": "uri", "description": "Where a subscriber recovers a lost key.", "examples": [ "https://filings.tools/billing/regenerate" ] }, "pages": { "type": "integer", "description": "413 and some 429 answers: the page count the request needs." }, "remaining": { "type": "integer", "description": "Some 429 answers: pages left." }, "maxPagesPerFile": { "type": "integer", "description": "413: the longest file this caller may convert." } } }, "Standing": { "type": "object", "description": "A caller's own standing. Reading it uses none of the allowance.", "required": [ "product", "caller", "limitKind", "unit", "limit", "remaining", "used", "reset", "resetIso", "persistent", "unavailable", "recover", "pricing" ], "properties": { "product": { "type": "string", "enum": [ "pdfmd", "filings" ] }, "caller": { "type": "string", "enum": [ "anon", "key" ] }, "label": { "type": "string", "description": "The plan name for a key." }, "plan": { "type": "string", "description": "The plan lookup key for a key, for example pdfmd_pro_monthly." }, "limitKind": { "type": "string", "enum": [ "calls_day", "pages_day", "pages_month" ] }, "unit": { "type": "string", "enum": [ "calls", "pages" ] }, "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "used": { "type": "integer" }, "maxPagesPerFile": { "type": "integer", "description": "Free tiers of pdfmd: the longest file one request may convert." }, "reset": { "type": "integer", "description": "Unix seconds." }, "resetIso": { "type": "string", "format": "date-time" }, "backend": { "type": "string", "enum": [ "upstash", "memory" ] }, "persistent": { "type": "boolean", "description": "True when the count is in shared storage. False means it is held per instance and a deploy resets it." }, "unavailable": { "type": "boolean", "description": "True when a key was sent and the store could not confirm it." }, "recover": { "type": "string", "format": "uri" }, "pricing": { "type": "string", "format": "uri" }, "free_key": { "type": "string", "format": "uri", "description": "Only for a caller without a key." } } }, "Company": { "type": "object", "description": "A company in the SEC ticker list.", "required": [ "cik", "ticker", "name" ], "properties": { "cik": { "type": "integer", "examples": [ 1045810 ] }, "ticker": { "type": "string", "examples": [ "NVDA" ] }, "name": { "type": "string", "examples": [ "NVIDIA CORP" ] }, "sic": { "type": "string" }, "sicDescription": { "type": "string" }, "fiscalYearEnd": { "type": "string", "description": "MMDD.", "examples": [ "0126" ] } } }, "FilingSummary": { "type": "object", "required": [ "id", "form", "filingDate", "accession", "sourceUrl", "pageUrl", "sectionsUrl" ], "properties": { "id": { "type": "string", "pattern": "^[0-9]+-[0-9]{18}$", "description": "CIK, a dash, and the accession number without dashes. Use it in the other routes.", "examples": [ "1045810-000104581026000021" ] }, "form": { "type": "string", "examples": [ "10-K" ] }, "filingDate": { "type": "string", "format": "date" }, "reportDate": { "type": "string", "description": "The period of the report, YYYY-MM-DD. Can be empty for an 8-K." }, "accession": { "type": "string", "examples": [ "0001045810-26-000021" ] }, "sourceUrl": { "type": "string", "format": "uri", "description": "The primary document on sec.gov." }, "pageUrl": { "type": "string", "format": "uri", "description": "The reader page on filings.tools." }, "sectionsUrl": { "type": "string", "format": "uri", "description": "The sections route for this filing." } } }, "FilingList": { "type": "object", "required": [ "company", "filings" ], "properties": { "company": { "$ref": "#/components/schemas/Company" }, "filings": { "type": "array", "items": { "$ref": "#/components/schemas/FilingSummary" } } } }, "Section": { "type": "object", "required": [ "id", "title", "markdown", "chars" ], "properties": { "id": { "type": "string", "description": "A stable slug.", "examples": [ "item-1a" ] }, "title": { "type": "string", "examples": [ "Item 1A. Risk Factors" ] }, "markdown": { "type": "string" }, "chars": { "type": "integer" } } }, "ParsedFiling": { "type": "object", "description": "A filing split into sections.", "required": [ "id", "product", "title", "sections", "topics", "parserVersion", "meta" ], "properties": { "id": { "type": "string" }, "product": { "type": "string", "enum": [ "filings" ] }, "title": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/Section" } }, "topics": { "type": "array", "items": { "type": "string" } }, "parserVersion": { "type": "string" }, "meta": { "type": "object", "description": "ticker, cik, form, accession, filingDate, reportDate and slug.", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } } } }, "Fact": { "type": "object", "required": [ "concept", "value", "unit", "end", "form", "filed", "accession" ], "properties": { "concept": { "type": "string", "examples": [ "Revenues" ] }, "friendly": { "type": "string", "enum": [ "revenue", "netIncome", "epsDiluted", "totalAssets", "cash", "longTermDebt", "sharesOutstanding", "operatingIncome", "capex", "operatingCashFlow" ] }, "value": { "type": "number" }, "unit": { "type": "string", "examples": [ "USD" ] }, "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" }, "fy": { "type": "integer" }, "fp": { "type": "string", "examples": [ "FY" ] }, "form": { "type": "string" }, "filed": { "type": "string", "format": "date" }, "accession": { "type": "string" } } }, "FactsResult": { "type": "object", "required": [ "company", "filing", "facts" ], "properties": { "company": { "$ref": "#/components/schemas/Company" }, "filing": { "type": "object", "required": [ "id", "form", "accession", "filingDate", "sourceUrl" ], "properties": { "id": { "type": "string" }, "form": { "type": "string" }, "accession": { "type": "string" }, "filingDate": { "type": "string", "format": "date" }, "reportDate": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" } } }, "facts": { "type": "array", "items": { "$ref": "#/components/schemas/Fact" } } } }, "Counts": { "type": "object", "required": [ "added", "removed", "changed", "unchanged" ], "properties": { "added": { "type": "integer" }, "removed": { "type": "integer" }, "changed": { "type": "integer" }, "unchanged": { "type": "integer" } } }, "FilingRef": { "type": "object", "required": [ "accession", "filingDate", "url", "page" ], "properties": { "accession": { "type": "string" }, "filingDate": { "type": "string", "format": "date" }, "reportDate": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "page": { "type": "string", "description": "Path of the reader page on filings.tools." } } }, "SectionDiff": { "type": "object", "required": [ "id", "title", "added", "removed", "changed", "counts" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "added": { "type": "array", "items": { "type": "string" }, "description": "Sentences that are only in the current filing. A limited sample." }, "removed": { "type": "array", "items": { "type": "string" }, "description": "Sentences that are only in the prior filing. A limited sample." }, "changed": { "type": "array", "items": { "type": "object", "required": [ "before", "after", "similarity" ], "properties": { "before": { "type": "string" }, "after": { "type": "string" }, "similarity": { "type": "number" } } } }, "counts": { "$ref": "#/components/schemas/Counts" }, "onlyIn": { "type": "string", "enum": [ "prior", "current" ], "description": "The section exists in one of the two filings only." }, "furniture": { "type": "object", "description": "Repeated page headers and footers of the section, compared apart from the content.", "additionalProperties": true } } }, "Comparison": { "type": "object", "description": "The filing compared with the preceding available filing of the same form. Counts and limited samples, not a full redline.", "required": [ "id", "ticker", "form", "comparable", "current", "prior", "counting", "diffRulesVersion", "totals", "furniture", "sections" ], "properties": { "id": { "type": "string" }, "ticker": { "type": "string" }, "company": { "type": "string" }, "form": { "type": "string" }, "comparable": { "type": "boolean", "enum": [ true ] }, "current": { "$ref": "#/components/schemas/FilingRef" }, "prior": { "$ref": "#/components/schemas/FilingRef" }, "counting": { "type": "string", "description": "What totals and counts measure." }, "diffRulesVersion": { "type": "string", "description": "Which counting rules made these numbers." }, "totals": { "$ref": "#/components/schemas/Counts" }, "furniture": { "$ref": "#/components/schemas/Counts" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/SectionDiff" } } } }, "NotComparable": { "type": "object", "description": "A 200 answer with a reason. The earliest filing of a form has nothing to compare against, and that is not an error.", "required": [ "id", "ticker", "form", "reportDate", "current", "comparable", "reason", "message" ], "properties": { "id": { "type": "string" }, "ticker": { "type": "string" }, "form": { "type": "string" }, "reportDate": { "type": "string" }, "current": { "$ref": "#/components/schemas/FilingRef" }, "comparable": { "type": "boolean", "enum": [ false ] }, "reason": { "type": "string", "enum": [ "no_prior", "unresolved" ], "description": "The code may take other values in the future." }, "message": { "type": "string" } } }, "UnknownCompany": { "type": "object", "required": [ "error", "message", "search", "suggestions" ], "properties": { "error": { "type": "string", "enum": [ "unknown_ticker", "unknown_cik" ] }, "ticker": { "type": "string" }, "cik": { "type": [ "integer", "string" ] }, "message": { "type": "string" }, "search": { "type": "string", "format": "uri", "examples": [ "https://www.sec.gov/search-filings" ] }, "suggestions": { "type": "array", "description": "Close matches. Empty for a CIK.", "items": { "type": "object", "required": [ "ticker", "cik", "name" ], "properties": { "ticker": { "type": "string" }, "cik": { "type": "integer" }, "name": { "type": "string" } } } } } }, "Unavailable": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "edgar_busy", "edgar_unavailable", "billing_store_unavailable" ] }, "message": { "type": "string" }, "retryAfter": { "type": "integer", "description": "Seconds. Also in the Retry-After header. Not set for billing_store_unavailable." } } }, "FilingTables": { "type": "object", "description": "Tables as JSON, when `format=json`.", "required": [ "filing", "company", "sections" ], "properties": { "filing": { "type": "object", "additionalProperties": true }, "company": { "type": "object", "additionalProperties": true }, "sections": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "tables" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "tables": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } }, "responses": { "RateLimited": { "description": "The daily or monthly allowance is used up. Without a key the body names the free key. Reset time is in `X-RateLimit-Reset`. The count is in calls.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-RateLimit-Unit": { "$ref": "#/components/headers/XRateLimitUnit" }, "X-Caller": { "$ref": "#/components/headers/XCaller" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "example": { "error": "rate_limited", "message": "Daily limit of 25 calls reached. It resets at 00:00 UTC.", "free_key": "https://filings.tools/billing/free", "pricing": "https://filings.tools/pricing", "recover": "https://filings.tools/billing/regenerate" } } } }, "TrialEnded": { "description": "A trial key has ended. Choose a plan to keep using the API.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "pricing" ], "properties": { "error": { "type": "string", "enum": [ "trial_ended" ] }, "message": { "type": "string" }, "pricing": { "type": "string", "format": "uri" } } }, "example": { "error": "trial_ended", "message": "This trial key has ended. Choose a plan to keep using the API.", "pricing": "https://filings.tools/pricing" } } } }, "InvalidKey": { "description": "The supplied key is invalid or inactive. Check the key or remove the authentication header to use the anonymous tier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_api_key", "message": "The API key is not valid for this service." } } } }, "Unauthorized": { "description": "No key was sent to a route that needs a subscription key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "plan_required", "message": "Send your API key in x-api-key." } } } } } } }