{"openapi":"3.1.0","info":{"title":"NetNest Design Fundamentals API","version":"1.0.0","description":"Company fundamentals from SEC 10-K and 10-Q filings: revenue, net income, EPS, cash flow, balance sheet items, with the source filing on every value. Data from SEC filings. Not investment advice.","contact":{"name":"NetNest Design LLC","email":"registrations@netnestdesign.com","url":"https://api.netnestdesign.com/docs"},"termsOfService":"https://api.netnestdesign.com/terms"},"servers":[{"url":"https://api.netnestdesign.com"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key from POST /v1/signup, sent as Authorization: Bearer nnf_..."},"x402":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 per call payment in USDC on eip155:8453: $0.02 a call on every paid endpoint, $0.05 a call on /v1/events."}},"schemas":{"MetricValue":{"type":"object","required":["metric","value","unit","period_type","derived"],"properties":{"metric":{"type":"string","enum":["revenue","net_income","eps_basic","eps_diluted","operating_income","total_assets","total_liabilities","equity","cash","operating_cash_flow","capex","free_cash_flow","shares_outstanding","revenue_contract"]},"value":{"type":["number","null"],"description":"The value. Null when not reported, with a reason."},"unit":{"type":"string","description":"Currency code (USD, CAD, ...), USD/shares style per share unit, or shares."},"period_type":{"type":"string","enum":["annual","quarterly","ttm"]},"period_start":{"type":["string","null"],"format":"date"},"period_end":{"type":["string","null"],"format":"date"},"fiscal_year":{"type":["integer","null"]},"fiscal_period":{"type":["string","null"],"enum":["FY","Q1","Q2","Q3","Q4",null]},"form":{"type":["string","null"],"description":"SEC form that reported the value, for example 10-K, 10-Q, 10-K/A."},"filed_date":{"type":["string","null"],"format":"date"},"accession_number":{"type":["string","null"]},"source_url":{"type":["string","null"],"format":"uri","description":"SEC filing index page."},"concept":{"type":["string","null"],"description":"XBRL concept used, for example us-gaap:Revenues."},"derived":{"type":"boolean","description":"True when calculated from other reported values (Q4, TTM, free cash flow)."},"stale":{"type":"boolean"},"restated":{"type":"boolean","description":"True when a later filing changed the originally reported value."},"derivation":{"type":"object","description":"Formula and inputs, present when derived is true."},"reason":{"type":"string","description":"Why the value is null."},"concept_changed":{"type":"boolean","description":"Revenue only. True when the reported concept changed and the values are not shown to be comparable across the change."},"concept_change":{"type":"object","description":"Revenue only, with concept_changed: old_concept, new_concept, overlap_periods and overlap_difference_pct."},"revenue_standard":{"type":["string","null"],"enum":["ASC 605","ASC 606",null],"description":"Revenue only. ASC 605 or ASC 606 for the period, or null with revenue_standard_reason. Set from the company's own SEC filings: the date it adopted ASC 606 and the transition method its filing states. A period before adoption reads ASC 606 only when the company states the full retrospective method and the value comes from a filing for a period that ended on or after adoption. A value from a filing whose fiscal year began before December 16, 2016 reads ASC 605."},"revenue_standard_reason":{"type":"string","enum":["period spans adoption","adoption date unknown","inputs reported under different standards","transition method pending a check of the filing text","transition method not found in the adoption filing","transition method differs between the company filings","adoption filing not found","adoption date in the filing text is outside the possible range","adoption date conflicts with the company's own filings","period before SEC registration, method unknown","before adoption or tagging error, unconfirmed"],"description":"Revenue only. Present whenever revenue_standard is null; says why."}}},"Company":{"type":"object","description":"Company profile with its latest 10-K and 10-Q."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Event":{"type":"object","description":"One fact from one SEC filing: an 8-K item, a Form 4 transaction row or a Schedule 13D or 13G stake. Facts from the filing only.","required":["id","type","name","form","filed","accepted_at","accession","url","cik","fields","cursor"],"properties":{"id":{"type":"string","description":"The accession number and a three digit place within the filing."},"type":{"type":"string","enum":["8k_material_agreement","8k_bankruptcy","8k_acquisition_completed","8k_results","8k_obligation_triggered","8k_listing_notice","8k_accountant_change","8k_non_reliance","8k_officer_director_change","8k_regulation_fd","8k_other_events","form4_transaction","13d_stake","13g_stake"]},"name":{"type":"string","description":"The event type in plain words, for example the 8-K item name."},"form":{"type":"string","enum":["8-K","8-K/A","4","4/A","SCHEDULE 13D","SCHEDULE 13D/A","SCHEDULE 13G","SCHEDULE 13G/A"]},"filed":{"type":"string","format":"date"},"accepted_at":{"type":"string","format":"date-time","description":"EDGAR acceptance time, UTC."},"observed_at":{"type":["string","null"],"format":"date-time","description":"When the feed first saw the filing. Null for history loaded from the daily indexes."},"accession":{"type":"string"},"url":{"type":"string","format":"uri","description":"SEC filing index page."},"cik":{"type":"integer","description":"The company the event is about: the filer of an 8-K, the issuer of a Form 4, the subject of a 13D or 13G."},"ticker":{"type":["string","null"],"description":"Null when the company has no listed ticker."},"fields":{"type":"object","description":"The facts from the filing for this event type; the keys per type are listed under Events in /docs."},"cursor":{"type":"string","description":"This event as a cursor, for since or before."}}}}},"paths":{"/v1/search":{"get":{"operationId":"searchCompany","summary":"Find a company by ticker or name (free)","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}],"responses":{"200":{"description":"Matches"}}}},"/v1/company/{ticker}":{"get":{"operationId":"getCompany","summary":"Company profile and latest key metrics","description":"Latest revenue, net income, diluted EPS, operating income, total assets, cash, free cash flow and shares outstanding for annual, quarterly and TTM periods. x402 price $0.02.","security":[{"bearer":[]},{"x402":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","example":"AAPL"},"description":"Ticker. BRK.B, BRK-B and brk.b all work."}],"responses":{"200":{"description":"Company and latest values"},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"402":{"description":"Payment required. The `PAYMENT-REQUIRED` header carries the x402 payment requirements."},"404":{"description":"Unknown ticker","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"422":{"description":"No US GAAP 10-K or 10-Q data for this company","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Rate or plan limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/v1/fundamentals/{ticker}":{"get":{"operationId":"getFundamentals","summary":"Latest values of chosen metrics","description":"Latest value of each requested metric for one period type, with source filing fields. x402 price $0.02.","security":[{"bearer":[]},{"x402":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","example":"AAPL"},"description":"Ticker. BRK.B, BRK-B and brk.b all work."},{"name":"metrics","in":"query","schema":{"type":"string","example":"revenue,net_income,eps_diluted"},"description":"Comma separated. Default: all except revenue_contract. Allowed: revenue, net_income, eps_basic, eps_diluted, operating_income, total_assets, total_liabilities, equity, cash, operating_cash_flow, capex, free_cash_flow, shares_outstanding, revenue_contract. revenue = total revenue as reported on the income statement; revenue_contract = revenue from contracts with customers (ASC 606), on request only."},{"name":"period","in":"query","schema":{"type":"string","enum":["annual","quarterly","ttm"],"default":"annual"}}],"responses":{"200":{"description":"Latest values"},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"402":{"description":"Payment required. The `PAYMENT-REQUIRED` header carries the x402 payment requirements."},"404":{"description":"Unknown ticker","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"422":{"description":"No US GAAP 10-K or 10-Q data for this company","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Rate or plan limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/v1/history/{ticker}/{metric}":{"get":{"operationId":"getHistory","summary":"One metric over time","description":"Values newest first, each with its source filing. x402 price $0.02.","security":[{"bearer":[]},{"x402":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","example":"AAPL"},"description":"Ticker. BRK.B, BRK-B and brk.b all work."},{"name":"metric","in":"path","required":true,"schema":{"type":"string","enum":["revenue","net_income","eps_basic","eps_diluted","operating_income","total_assets","total_liabilities","equity","cash","operating_cash_flow","capex","free_cash_flow","shares_outstanding","revenue_contract"]}},{"name":"period","in":"query","schema":{"type":"string","enum":["annual","quarterly","ttm"],"default":"annual"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":20}}],"responses":{"200":{"description":"History"},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"402":{"description":"Payment required. The `PAYMENT-REQUIRED` header carries the x402 payment requirements."},"404":{"description":"Unknown ticker","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"422":{"description":"No US GAAP 10-K or 10-Q data for this company","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Rate or plan limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/v1/signup":{"post":{"operationId":"signup","summary":"Create a free account and get a key (10 calls a day until the email is verified, then 100)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"Account created; the key is in api_key and is shown once. The key has a small daily quota until the email is verified"},"409":{"description":"Email already registered"}}}},"/v1/signup/verify":{"post":{"operationId":"verifyEmail","summary":"Verify the account email with the code from the welcome email, or request a fresh code","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"The 64 character code from the email"}}},{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}]}}}},"responses":{"200":{"description":"Verified; the free plan now has its full daily quota"},"202":{"description":"A fresh code is on its way if an unverified account uses this email"},"410":{"description":"Code used or expired"}}}},"/v1/account":{"get":{"operationId":"getAccount","summary":"Plan, usage and keys","security":[{"bearer":[]}],"responses":{"200":{"description":"Account"}}},"delete":{"operationId":"deleteAccount","summary":"Delete the account, its keys and usage records","security":[{"bearer":[]}],"responses":{"200":{"description":"Deleted"}}}},"/v1/keys/rotate":{"post":{"operationId":"rotateKey","summary":"Issue a new key and revoke the current one","security":[{"bearer":[]}],"responses":{"201":{"description":"New key"}}}},"/v1/keys/current":{"delete":{"operationId":"revokeKey","summary":"Revoke the current key","security":[{"bearer":[]}],"responses":{"200":{"description":"Revoked"}}}},"/v1/events":{"get":{"operationId":"getEvents","summary":"SEC filing events across companies, newest first","description":"One feed of 8-K items, Form 4 insider transactions and Schedule 13D and 13G stakes, newest first, within about a minute of EDGAR, with a cursor to poll on. next is the cursor to poll with next time. It is null only when the feed holds no event yet: poll again without since. x402 price $0.05. Counts as 3 calls on a plan.","security":[{"bearer":[]},{"x402":[]}],"parameters":[{"name":"since","in":"query","schema":{"type":"string"},"description":"Cursor from an earlier answer (its next field): only events newer than it are returned"},{"name":"before","in":"query","schema":{"type":"string"},"description":"Cursor from an earlier answer (its continue field): the next page of older events"},{"name":"types","in":"query","schema":{"type":"string","example":"8k_results,form4_transaction"},"description":"Comma separated. Event types to include, for example 8k_results or form4_transaction. Allowed: 8k_material_agreement, 8k_bankruptcy, 8k_acquisition_completed, 8k_results, 8k_obligation_triggered, 8k_listing_notice, 8k_accountant_change, 8k_non_reliance, 8k_officer_director_change, 8k_regulation_fd, 8k_other_events, form4_transaction, 13d_stake, 13g_stake."},{"name":"tickers","in":"query","schema":{"type":"string","example":"AAPL,MSFT"},"description":"Comma separated. Tickers to include, for example AAPL or BRK.B."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"count":{"type":"integer"},"next":{"type":["string","null"],"description":"next is the cursor to poll with next time. It is null only when the feed holds no event yet: poll again without since."},"continue":{"type":["string","null"],"description":"The cursor for the next page of older events when more than limit were newer than since; else null."},"head":{"type":["string","null"],"description":"The newest cursor in the feed."}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"402":{"description":"Payment required. The `PAYMENT-REQUIRED` header carries the x402 payment requirements."},"410":{"description":"The cursor is ahead of the feed head (cursor_expired); the body carries the current head.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Rate or plan limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/v1/events/head":{"get":{"operationId":"getEventsHead","summary":"The latest events cursor and how many events are newer than yours (free)","description":"Free: the newest cursor of the SEC events feed and, given a cursor, how many events are newer than it, so a poller pays only when there is something new. Data from SEC filings. Not investment advice.","parameters":[{"name":"since","in":"query","schema":{"type":"string"},"description":"Cursor from an earlier answer (its next field): only events newer than it are returned"}],"responses":{"200":{"description":"Head and count","content":{"application/json":{"schema":{"type":"object","properties":{"head":{"type":["string","null"]},"count":{"type":"integer"}}}}}},"400":{"description":"Invalid cursor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"410":{"description":"The cursor is ahead of the feed head (cursor_expired); the body carries the current head.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Rate limit reached","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/v1/status":{"get":{"operationId":"getStatus","summary":"Data refresh health (free)","responses":{"200":{"description":"Status"}}}},"/v1/accuracy":{"get":{"operationId":"getAccuracy","summary":"Daily accuracy check against the filings (free)","responses":{"200":{"description":"Results"}}}}}}