{"openapi":"3.1.0","info":{"title":"value.today API","version":"1.2","description":"Company rankings, financial statements as reported (point in time), ownership, restatements, identifiers, survivorship-bias-free samples and economic data with first prints. Amounts in USD millions unless an endpoint says otherwise. Every figure names its official source; cite the data as the methodology page says.","termsOfService":"https://www.value.today/developers","contact":{"url":"https://www.value.today/developers"}},"servers":[{"url":"https://www.value.today/api/v1"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"security":[{"ApiKey":[]}],"externalDocs":{"description":"Methodology and definitions","url":"https://www.value.today/methodology"},"paths":{"/companies/":{"get":{"tags":["Companies"],"summary":"Companies, ranked","operationId":"companies","parameters":[{"name":"country__slug","in":"query","required":false,"description":"Country","schema":{"type":"string"},"example":"india"},{"name":"sector__slug","in":"query","required":false,"description":"Sector","schema":{"type":"string"}},{"name":"industry__slug","in":"query","required":false,"description":"Industry","schema":{"type":"string"}},{"name":"listing_status","in":"query","required":false,"description":"listed or unlisted","schema":{"type":"string","enum":["listed","unlisted"]}},{"name":"market_cap_min","in":"query","required":false,"description":"Market cap at least (USD m)","schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"description":"Words in the name","schema":{"type":"string"}},{"name":"ordering","in":"query","required":false,"description":"Sort, e.g. -market_cap, -revenue, -employees, pe_ratio, updated_at","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"Only companies changed at or after this moment (ISO date and time): with ordering=updated_at, keeps a copy in step","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page (50 a page)","schema":{"type":"integer"}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Listed and unlisted companies, largest first. Amounts in USD millions."}},"/companies/{slug}/":{"get":{"tags":["Companies"],"summary":"One company","operationId":"companies_slug","parameters":[{"name":"slug","in":"path","required":true,"description":"The company's address on value.today (from /companies/ or /research/identifiers/)","schema":{"type":"string"},"example":"apple"}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Profile, financial history in USD, quarterly results, filings, people, rank history, sources, ownership and industry benchmarks."}},"/companies/{slug}/financial-statements/":{"get":{"tags":["Companies"],"summary":"Financial statements as reported, point in time","operationId":"companies_slug_financial_statements","parameters":[{"name":"slug","in":"path","required":true,"description":"The company's address on value.today (from /companies/ or /research/identifiers/)","schema":{"type":"string"},"example":"apple"},{"name":"basis","in":"query","required":false,"description":"latest (default) or first: every figure as first reported","schema":{"type":"string","enum":["latest","first"]}},{"name":"as_of","in":"query","required":false,"description":"A day, YYYY-MM-DD: only what had been filed by that day, each figure as it stood then","schema":{"type":"string","format":"date"},"example":"2015-06-30"},{"name":"years","in":"query","required":false,"description":"Fiscal years to give (up to 40)","schema":{"type":"integer"}},{"name":"quarters","in":"query","required":false,"description":"Quarters to give (up to 40)","schema":{"type":"integer"}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Income statement, balance sheet and cash-flow statement by fiscal year and quarter, in the reported currency and full units, each figure with its filing and XBRL concept. A figure changed after its first report carries its first value and filing. Definitions: https://www.value.today/methodology#as-first-reported"}},"/search/":{"get":{"tags":["Companies"],"summary":"Search companies, people, funds, brands, indices, countries and pages","operationId":"search","parameters":[{"name":"q","in":"query","required":false,"description":"Words or an identifier to look for","schema":{"type":"string"},"example":"infosys"},{"name":"limit","in":"query","required":false,"description":"How many results (up to 50)","schema":{"type":"integer"}},{"name":"type","in":"query","required":false,"description":"Only one group","schema":{"type":"string","enum":["companies","people","funds","products","markets","places","lists","pages"]}},{"name":"per_group","in":"query","required":false,"description":"Also this many results of each group (up to 10)","schema":{"type":"integer"}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Typo-tolerant: a name, part of one, a ticker, an ISIN, an LEI or a CIK. `results` are the best matches in order, each with its kind and the page it leads to; `groups` the same by kind (with per_group or type)."}},"/ask/":{"get":{"tags":["Companies"],"summary":"A question in plain English","operationId":"ask","parameters":[{"name":"q","in":"query","required":false,"description":"The question","schema":{"type":"string"},"example":"top 10 Indian pharma companies by revenue"}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Answered from the database by rules (no language model)."}},"/countries/":{"get":{"tags":["Groups"],"summary":"Totals by country","operationId":"countries","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/sectors/":{"get":{"tags":["Groups"],"summary":"Totals by sector","operationId":"sectors","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/world/":{"get":{"tags":["Groups"],"summary":"Market cap by country, continent and sector","operationId":"world","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/rankings/snapshot-dates/":{"get":{"tags":["Market caps"],"summary":"The dates of the market-cap snapshots since 2020","operationId":"rankings_snapshot_dates","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/rankings/snapshot/":{"get":{"tags":["Market caps"],"summary":"The ranking at one snapshot, delisted companies included","operationId":"rankings_snapshot","parameters":[{"name":"date","in":"query","required":false,"description":"A day, YYYY-MM-DD","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"description":"How many","schema":{"type":"integer"}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Every company valued at that snapshot, including those that have since left the market."}},"/leaders/":{"get":{"tags":["People and deals"],"summary":"Business leaders and billionaires","operationId":"leaders","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/deals/":{"get":{"tags":["People and deals"],"summary":"Acquisitions","operationId":"deals","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/startups/":{"get":{"tags":["People and deals"],"summary":"Startups and their funding","operationId":"startups","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/filings/latest/":{"get":{"tags":["Filings"],"summary":"The newest SEC filings","operationId":"filings_latest","parameters":[{"name":"type","in":"query","required":false,"description":"earnings, annual or quarterly","schema":{"type":"string","enum":["earnings","annual","quarterly"]}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/fx/":{"get":{"tags":["Currencies"],"summary":"Today's exchange rates used for conversions (units per USD)","operationId":"fx","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/exchange-rates/":{"get":{"tags":["Currencies"],"summary":"Every currency against the US dollar: the list","operationId":"exchange_rates","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/exchange-rates/{code}/":{"get":{"tags":["Currencies"],"summary":"One currency by month and year","operationId":"exchange_rates_code","parameters":[{"name":"code","in":"path","required":true,"description":"ISO 4217 currency code","schema":{"type":"string"},"example":"inr"}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Average and end-of-period rates against the US dollar (BIS) and the World Bank's yearly conversion factors. Definitions: https://www.value.today/methodology#average-exchange-rates"}},"/research/restatements/":{"get":{"tags":["Research"],"summary":"Restatements: figures changed after their first report","operationId":"research_restatements","parameters":[{"name":"line","in":"query","required":false,"description":"Statement line","schema":{"type":"string","enum":["revenue","net_income","operating_income","total_assets","total_equity","operating_cash_flow","eps_diluted"]}},{"name":"year","in":"query","required":false,"description":"Fiscal year","schema":{"type":"integer"}},{"name":"direction","in":"query","required":false,"description":"up or down","schema":{"type":"string","enum":["up","down"]}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Rates by line and fiscal year, and the largest changes with both filings. Definitions: https://www.value.today/methodology#as-first-reported"}},"/research/identifiers/":{"get":{"tags":["Research"],"summary":"Identifier lookup (crosswalk)","operationId":"research_identifiers","parameters":[{"name":"ids","in":"query","required":false,"description":"Up to 500, comma-separated or one per line","schema":{"type":"string"},"example":"AAPL,US0378331005,0000320193"}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Companies for a list of tickers, SEC CIKs, ISINs, LEIs, Wikidata items or names, with every identifier they carry. Definitions: https://www.value.today/methodology#identifier-lookup"}},"/research/index-members/":{"get":{"tags":["Research"],"summary":"An index's members on any day","operationId":"research_index_members","parameters":[{"name":"index","in":"query","required":false,"description":"SPX, NDX or NIFTY50","schema":{"type":"string","enum":["SPX","NDX","NIFTY50"]}},{"name":"date","in":"query","required":false,"description":"A day, YYYY-MM-DD","schema":{"type":"string","format":"date"},"example":"2008-09-15"}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Today's members with every recorded change since undone; unmatched additions are listed. Definitions: https://www.value.today/methodology#index-members-on-a-date"}},"/research/delisted/":{"get":{"tags":["Research"],"summary":"Delisted companies and how they left","operationId":"research_delisted","parameters":[{"name":"reason","in":"query","required":false,"description":"How it left (a key of `reasons` in the answer)","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"ISO 3166 code","schema":{"type":"string"},"example":"US"},{"name":"q","in":"query","required":false,"description":"Part of the name, or the ticker","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page (100 a page)","schema":{"type":"integer"}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Definitions: https://www.value.today/methodology#delisted-companies"}},"/indices/{code}/changes/":{"get":{"tags":["Research"],"summary":"Additions to and removals from an index","operationId":"indices_code_changes","parameters":[{"name":"code","in":"path","required":true,"description":"SPX, NDX, NIFTY50 or DJI","schema":{"type":"string"},"example":"SPX"}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"From Wikipedia's historical-components tables (CC BY-SA 4.0: attribute and share alike). Definitions: https://www.value.today/methodology#index-changes"}},"/methodology/":{"get":{"tags":["Research"],"summary":"Every metric's definition, formula, sources, schedule and coverage","operationId":"methodology","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/datasets/":{"get":{"tags":["Research"],"summary":"The research datasets: each with its newest file's rows, size and SHA-256, and the versions","operationId":"datasets","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"The files themselves are downloaded on /datasets by accounts with the download right. Definitions: https://www.value.today/methodology#research-datasets"}},"/datasets/{key}/":{"get":{"tags":["Research"],"summary":"One dataset's data dictionary, sources, terms, versions and first rows","operationId":"datasets_key","parameters":[{"name":"key","in":"path","required":true,"description":"Dataset key","schema":{"type":"string"},"example":"companies"},{"name":"version","in":"query","required":false,"description":"A day, YYYY-MM-DD","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Definitions: https://www.value.today/methodology#research-datasets"}},"/economy/":{"get":{"tags":["Economy"],"summary":"The latest figure of every major US release","operationId":"economy","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/economy/series/{key}/":{"get":{"tags":["Economy"],"summary":"One economic series","operationId":"economy_series_key","parameters":[{"name":"key","in":"path","required":true,"description":"Series key","schema":{"type":"string"},"example":"us-payrolls"}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Values, its main presentations, first prints and revisions."}},"/economy/revisions/":{"get":{"tags":["Economy"],"summary":"How much US first prints are revised","operationId":"economy_revisions","parameters":[{"name":"since","in":"query","required":false,"description":"Periods since 1990, 2000 (default), 2010 or 2020","schema":{"type":"string","enum":["1990","2000","2010","2020"]}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Definitions: https://www.value.today/methodology#first-print-revisions"}},"/economy/revisions/{key}/":{"get":{"tags":["Economy"],"summary":"One series' first prints, and the series as published on any day","operationId":"economy_revisions_key","parameters":[{"name":"key","in":"path","required":true,"description":"Series key","schema":{"type":"string"},"example":"us-payrolls"},{"name":"since","in":"query","required":false,"description":"Periods since","schema":{"type":"string","enum":["1990","2000","2010","2020"]}},{"name":"as_of","in":"query","required":false,"description":"A day, YYYY-MM-DD: the series as it stood that day","schema":{"type":"string","format":"date"},"example":"2020-05-01"}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Definitions: https://www.value.today/methodology#first-print-revisions"}},"/economy/calendar/":{"get":{"tags":["Economy"],"summary":"When the US releases come out","operationId":"economy_calendar","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/indicators/":{"get":{"tags":["Economy"],"summary":"The World Bank, IMF and BIS indicator catalogue","operationId":"indicators","parameters":[{"name":"q","in":"query","required":false,"description":"Words in the name or code","schema":{"type":"string"}},{"name":"topic","in":"query","required":false,"description":"Topic","schema":{"type":"string"}},{"name":"source","in":"query","required":false,"description":"wb, imf or bis","schema":{"type":"string","enum":["wb","imf","bis"]}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Names and coverage; the values of IMF series are not served to API keys (the IMF's terms)."}},"/indicators/{code}/":{"get":{"tags":["Economy"],"summary":"One indicator for every country, by year","operationId":"indicators_code","parameters":[{"name":"code","in":"path","required":true,"description":"Series code at the source","schema":{"type":"string"},"example":"NY.GDP.MKTP.CD"},{"name":"c","in":"query","required":false,"description":"Country slugs, comma-separated","schema":{"type":"string"}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"World Bank (CC BY 4.0) and BIS series; IMF series are refused to API keys."}},"/trade/":{"get":{"tags":["Economy"],"summary":"Exports and imports of every country: the list","operationId":"trade","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}}}},"/trade/{country}/{flow}/":{"get":{"tags":["Economy"],"summary":"One country's exports or imports by year, partner and product","operationId":"trade_country_flow","parameters":[{"name":"country","in":"path","required":true,"description":"Country page name","schema":{"type":"string"},"example":"india"},{"name":"flow","in":"path","required":true,"description":"exports or imports","schema":{"type":"string","enum":["exports","imports"]}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"World Bank, WITS, CEPII BACI and the Harvard Growth Lab, each row naming its source."}},"/status/":{"get":{"tags":["Status"],"summary":"Whether the site, the API and each data feed work now","operationId":"status","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"The data feeds' newest dates against their schedules, the data jobs of the last day and 30 days, and value.today's notices about incidents and maintenance. Needs no key."}},"/changes/":{"get":{"tags":["Sync"],"summary":"What changed since a moment","operationId":"changes","parameters":[{"name":"since","in":"query","required":false,"description":"An ISO date or date and time, UTC unless it says otherwise","schema":{"type":"string"},"example":"2026-11-18T06:00:00Z"}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Companies changed (and the address that lists them with updated_since), companies merged or removed, and the loads and edits of the period with their counts. Pass the answer's until as since next time. Up to 90 days back."}},"/sheets/values/":{"get":{"tags":["Spreadsheets"],"summary":"The latest figures of up to 100 companies, ready for a spreadsheet","operationId":"sheets_values","parameters":[{"name":"companies","in":"query","required":false,"description":"Companies, comma-separated","schema":{"type":"string"},"example":"AAPL,MSFT,US0378331005"},{"name":"fields","in":"query","required":false,"description":"Fields, comma-separated","schema":{"type":"string"},"example":"market_cap,revenue,roe"},{"name":"list","in":"query","required":false,"description":"A team list's number (team keys only)","schema":{"type":"integer"}},{"name":"as","in":"query","required":false,"description":"json (default), table or text","schema":{"type":"string","enum":["json","table","text"]}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Companies by ticker, ISIN, CIK, LEI, Wikidata item, exact name or value.today slug (the largest match wins); fields by key, label or alias. Each row carries its market cap's date and its statements' fiscal year. as=table gives one array of rows with a header row; as=text the one value alone (one company, one field). A team key may name one of its lists instead."}},"/sheets/history/":{"get":{"tags":["Spreadsheets"],"summary":"One yearly figure of one company over the years","operationId":"sheets_history","parameters":[{"name":"company","in":"query","required":false,"description":"A company, by any identifier","schema":{"type":"string"},"example":"AAPL"},{"name":"field","in":"query","required":false,"description":"A yearly figure","schema":{"type":"string"},"example":"revenue"},{"name":"years","in":"query","required":false,"description":"How many years, newest last (up to 30)","schema":{"type":"integer"}},{"name":"as","in":"query","required":false,"description":"json (default), table or text","schema":{"type":"string","enum":["json","table","text"]}}],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"Each year with its fiscal year end and its source (SEC, ESEF, the editors, Wikidata citing the annual report, market caps)."}},"/sheets/fields/":{"get":{"tags":["Spreadsheets"],"summary":"Every field the spreadsheet endpoints know","operationId":"sheets_fields","parameters":[],"responses":{"200":{"description":"JSON","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid API key"},"429":{"description":"Daily limit reached (see Retry-After)"}},"description":"With its unit and the methodology entry that defines it."}}}}