{"components":{"schemas":{"AnnualPeriod":{"properties":{"metrics":{"additionalProperties":{"$ref":"#/components/schemas/MetricObservation"},"description":"Canonical metric key to observation. A missing key means not reported, not zero.","type":"object"},"notes":{"additionalProperties":{"type":"string"},"description":"Metric or ratio key to why this year's figure is not comparable with the year before (do not compute a change across it), or why a ratio is null.","type":"object"},"period_end":{"format":"date","type":"string"},"period_year":{"type":"integer"},"ratios":{"additionalProperties":{"type":["number","null"]},"description":"Ratio key to value, computed by TickerFacts for this period: percent, except liabilities_to_equity and long_term_debt_to_equity (plain ratios). Null when an input is missing or incompatible, or the ratio means nothing (see notes).","type":"object"}},"required":["period_year","period_end","metrics"],"type":"object"},"CashflowInputs":{"properties":{"cik":{"type":"integer"},"dataset_built_at":{"type":"string"},"dataset_digest":{"type":"string"},"name":{"type":"string"},"periods":{"description":"Newest first; at most 15.","items":{"properties":{"currency":{"type":"string"},"facts":{"additionalProperties":{"$ref":"#/components/schemas/CashflowObservation"},"propertyNames":{"enum":["operating_cash_flow","capex","net_income","shares_outstanding"]},"type":"object"},"period_end":{"type":"string"},"period_start":{"type":["string","null"]}},"required":["period_end","period_start","currency","facts"],"type":"object"},"maxItems":15,"type":"array"},"ticker":{"type":["string","null"]}},"required":["ticker","cik","name","dataset_built_at","dataset_digest","periods"],"type":"object"},"CashflowObservation":{"properties":{"accession":{"type":"string"},"filed":{"type":"string"},"period_end":{"type":"string"},"period_start":{"type":["string","null"]},"source_url":{"type":"string"},"tag":{"type":"string"},"unit":{"type":"string"},"value":{"description":"Decimal STRING. Unlike /api/v1/companies, where values are JSON numbers.","pattern":"^-?[0-9]+(\\.[0-9]+)?$","type":"string"}},"required":["value","unit","period_start","period_end","filed","accession","tag","source_url"],"type":"object"},"Company":{"properties":{"annual":{"description":"Newest period end first.","items":{"$ref":"#/components/schemas/AnnualPeriod"},"type":"array"},"basis_breaks":{"description":"Years on a different basis from the year before (restated after a spin-off, discontinued operation or accounting change, while the year before kept its old basis). Do not compute a change or growth rate across one.","items":{"properties":{"metric":{"type":"string"},"period_end":{"format":"date","type":"string"}},"required":["metric","period_end"],"type":"object"},"type":"array"},"cik":{"type":"integer"},"coverage":{"$ref":"#/components/schemas/Coverage"},"data_quality":{"description":"Warnings about the figures themselves, such as out-of-scale values from a unit tagged wrongly.","items":{"type":"string"},"type":"array"},"dataset_built_at":{"type":"string"},"dataset_sha256":{"type":["string","null"]},"display_name":{"description":"Readable form of name for display; match filings on cik, not this.","type":"string"},"evidence_url":{"type":"string"},"exchange":{"type":["string","null"]},"latest_interim":{"properties":{"basis":{"type":"string"},"metrics":{"additionalProperties":{"$ref":"#/components/schemas/MetricObservation"},"description":"Trailing-twelve-month flows (with period_start) and latest quarterly balances (period_start null).","type":"object"},"period_end":{"format":"date","type":"string"}},"required":["period_end","basis","metrics"],"type":"object"},"listing_status":{"description":"former: the company has left SEC's current ticker directory; its figures are its last filings and will not update.","enum":["current","former"]},"metric_definitions":{"additionalProperties":{"$ref":"#/components/schemas/MetricDefinition"},"type":"object"},"name":{"description":"SEC conformed (legal) name, as filed.","type":"string"},"notice":{"description":"Figures may be incomplete or wrong and are not investment advice; keep this caveat when passing figures on.","type":"string"},"profile":{"$ref":"#/components/schemas/Profile"},"requested_ticker":{"type":["string","null"]},"research_url":{"type":"string"},"sec_history_url":{"type":"string"},"selection":{"$ref":"#/components/schemas/Selection"},"source":{"type":"string"},"stock_splits":{"description":"Detected from restated filings. Per-share figures and share counts filed before a split are on the old basis.","items":{"properties":{"first_filing_after":{"format":"date","type":"string"},"ratio":{"description":"4-for-1, or 1-for-10 for a reverse split.","type":"string"}},"required":["ratio","first_filing_after"],"type":"object"},"type":"array"},"successor":{"properties":{"cik":{"type":"integer"},"name":{"type":"string"}},"required":["cik","name"],"type":"object"},"terms":{"description":"Terms of use, which apply to API and agent use.","format":"uri","type":"string"},"ticker":{"type":["string","null"]},"valuation":{"$ref":"#/components/schemas/PriceValuation"}},"required":["notice","terms","dataset_built_at","dataset_sha256","requested_ticker","coverage","metric_definitions","research_url","sec_history_url","evidence_url","ticker","cik","name","display_name","listing_status","exchange","source","annual"],"type":"object"},"CompanyBatch":{"properties":{"count":{"minimum":0,"type":"integer"},"metric_definitions":{"additionalProperties":{"$ref":"#/components/schemas/MetricDefinition"},"description":"Definitions for every returned metric and ratio, once for the batch; each company's own metric_definitions is empty.","type":"object"},"results":{"items":{"properties":{"company":{"oneOf":[{"$ref":"#/components/schemas/Company"},{"type":"null"}]},"requested_ticker":{"type":"string"},"status":{"enum":["ok","not_found"]}},"required":["requested_ticker","status","company"],"type":"object"},"type":"array"}},"required":["count","results"],"type":"object"},"CompanyEvidence":{"properties":{"cik":{"type":"integer"},"coverage":{"type":"string"},"evidence_sha256":{"type":"string"},"limitations":{"type":"string"},"normalization":{"type":"string"},"passages":{"description":"Empty means no passage is reviewed for this company, not that no event occurred.","items":{"$ref":"#/components/schemas/ReviewedPassage"},"type":"array"},"requested_ticker":{"type":"string"},"reviewed_at":{"type":"string"},"schema_version":{"type":"integer"},"status":{"type":"string"},"ticker":{"type":"string"}},"required":["cik","ticker","status","coverage","passages"],"type":"object"},"CompanyResearch":{"properties":{"cik":{"type":"integer"},"company":{"description":"Null when no research record exists for this company.","oneOf":[{"$ref":"#/components/schemas/CompanyResearchRecord"},{"type":"null"}]},"research_built_at":{"type":"string"},"reviewed_events":{"items":{"$ref":"#/components/schemas/ReviewedPassage"},"type":"array"},"reviewed_events_coverage":{"type":"string"},"sources":{"items":{"$ref":"#/components/schemas/Source"},"type":"array"}},"required":["cik","research_built_at","sources","company","reviewed_events","reviewed_events_coverage"],"type":"object"},"CompanyResearchRecord":{"properties":{"entity_status":{"type":["string","null"]},"filings":{"items":{"properties":{"accession":{"type":"string"},"document":{"type":"string"},"filed":{"type":"string"},"form":{"type":"string"},"items":{"type":"string"},"report_date":{"type":"string"}},"required":["accession","form","filed","report_date","document","items"],"type":"object"},"type":"array"},"former_names":{"items":{"properties":{"from":{"type":"string"},"name":{"type":"string"},"to":{"type":"string"}},"required":["name","from","to"],"type":"object"},"type":"array"},"gleif_parents":{"items":{"$ref":"#/components/schemas/Parent"},"type":"array"},"headquarters":{"items":{"properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"name":{"type":"string"},"precision":{"type":"string"},"source":{"type":"string"},"url":{"type":"string"}},"required":["name","latitude","longitude","precision","source","url"],"type":"object"},"type":"array"},"insiders":{"items":{"properties":{"accession":{"type":"string"},"acquired_disposed":{"type":"string"},"code":{"type":"string"},"date":{"type":"string"},"derivative":{"type":"boolean"},"filed":{"type":"string"},"following_shares":{"description":"Decimal string, as reported.","type":["string","null"]},"form":{"type":"string"},"owners":{"items":{"type":"string"},"type":"array"},"plan_10b5_1":{"type":"boolean"},"price":{"description":"Decimal string, as reported.","type":["string","null"]},"security":{"type":"string"},"shares":{"description":"Decimal string, as reported.","type":["string","null"]}},"required":["accession","filed","form","owners","date","code","security","shares","price","acquired_disposed","following_shares","derivative","plan_10b5_1"],"type":"object"},"type":"array"},"legal_name":{"type":["string","null"]},"lei":{"type":["string","null"]},"lei_status":{"type":["string","null"]},"lei_updated_at":{"type":["string","null"]},"names":{"items":{"properties":{"entity_id":{"type":["string","null"]},"kind":{"type":"string"},"name":{"type":"string"},"source":{"type":"string"}},"required":["entity_id","name","kind","source"],"type":"object"},"type":"array"},"parent_exceptions":{"items":{"type":"string"},"type":"array"},"parents":{"items":{"$ref":"#/components/schemas/Parent"},"type":"array"},"wikidata_id":{"type":["string","null"]}},"required":["names","former_names","filings","insiders","wikidata_id","headquarters","parents","lei","legal_name","entity_status","lei_status","lei_updated_at","gleif_parents","parent_exceptions"],"type":"object"},"CompanySearch":{"properties":{"count":{"minimum":0,"type":"integer"},"note":{"type":"string"},"query":{"type":"string"},"results":{"items":{"properties":{"cik":{"type":"integer"},"exchange":{"type":["string","null"]},"industry":{"type":["string","null"]},"latest_period_end":{"type":["string","null"]},"listing_status":{"enum":["current","former"]},"matched":{"enum":["ticker","name","similar"]},"name":{"type":"string"},"sector":{"type":["string","null"]},"ticker":{"type":"string"}},"required":["ticker","name","cik","listing_status","matched"],"type":"object"},"type":"array"}},"required":["query","count","results"],"type":"object"},"CountyCandidates":{"properties":{"ambiguous":{"const":true},"candidates":{"items":{"properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":"string"},"state_name":{"type":"string"}},"required":["id","name","state","state_name"],"type":"object"},"type":"array"},"hint":{"type":"string"},"match_count":{"type":"integer"},"query":{"type":"string"},"showing":{"type":"integer"}},"required":["ambiguous","query","match_count","showing","candidates","hint"],"type":"object"},"CountyContext":{"properties":{"accuracy_url":{"type":["string","null"]},"built_at":{"type":"string"},"id":{"description":"County FIPS code.","pattern":"^[0-9]{5}$","type":"string"},"interpretation":{"type":"string"},"name":{"type":"string"},"notes":{"items":{"type":"string"},"type":"array"},"population":{"type":["object","null"]},"private_industry_employment":{"items":{"$ref":"#/components/schemas/CountyIndustry"},"type":"array"},"resident_characteristics":{"items":{"properties":{"id":{"type":"string"},"kind":{"type":["string","null"]},"label":{"type":"string"},"margin_of_error_90pct":{"type":["number","null"]},"period":{"type":["string","null"]},"price_basis":{"type":["string","null"]},"source":{"type":["string","null"]},"uncertainty":{"type":["string","null"]},"unit":{"type":["string","null"]},"universe":{"type":["string","null"]},"value":{"description":"Null means unavailable, not zero.","type":["number","null"]}},"required":["id","label","value","margin_of_error_90pct"],"type":"object"},"type":"array"},"sources":{"items":{"type":"object"},"type":"array"},"state":{"type":"string"},"state_name":{"type":"string"},"version":{"type":"integer"}},"required":["id","name","state","state_name","population","resident_characteristics","private_industry_employment","built_at","sources","notes","interpretation"],"type":"object"},"CountyIndustry":{"properties":{"annual_pay_usd":{"type":["number","null"]},"disclosure":{"type":["string","null"]},"job_growth_pct":{"type":["number","null"]},"jobs":{"type":["number","null"]},"label":{"type":["string","null"]},"naics":{"type":"string"},"national":{"description":"The same columns for the whole country.","type":"object"},"weekly_wage_usd":{"type":["number","null"]}},"required":["naics","label","jobs","annual_pay_usd","weekly_wage_usd","job_growth_pct","disclosure"],"type":"object"},"Coverage":{"properties":{"annual_periods_available":{"minimum":0,"type":"integer"},"entity_continuity":{"type":"string"},"history_basis":{"type":"string"},"latest_observation_filed":{"type":["string","null"]},"latest_period_end":{"type":["string","null"]},"limitations":{"items":{"type":"string"},"type":"array"},"missing_metrics_latest_period":{"items":{"type":"string"},"type":"array"},"missing_reason":{"type":"string"},"status":{"type":"string"}},"required":["status","annual_periods_available","latest_period_end","latest_observation_filed","missing_metrics_latest_period","missing_reason","history_basis","entity_continuity","limitations"],"type":"object"},"EconomicContext":{"properties":{"built_at":{"type":"string"},"series":{"items":{"properties":{"frequency":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"observations":{"items":{"properties":{"date":{"type":"string"},"value":{"description":"Decimal string, as published.","type":"string"}},"required":["date","value"],"type":"object"},"type":"array"},"source":{"type":"string"},"unit":{"type":"string"}},"required":["id","name","unit","frequency","source","observations"],"type":"object"},"type":"array"},"sources":{"items":{"$ref":"#/components/schemas/Source"},"type":"array"}},"required":["built_at","sources","series"],"type":"object"},"Error":{"properties":{"error":{"type":"string"}},"required":["error"],"type":"object"},"MetricDefinition":{"properties":{"accepted_tags":{"items":{"type":"string"},"type":"array"},"interpretation":{"type":"string"},"label":{"type":"string"},"period_type":{"type":"string"}},"required":["label","period_type","accepted_tags","interpretation"],"type":"object"},"MetricObservation":{"properties":{"accession":{"description":"SEC accession number of the source filing.","type":"string"},"derivation":{"description":"Present only on metrics TickerFacts computes (free_cash_flow): the arithmetic used. Absent on reported figures.","type":"string"},"filed":{"format":"date","type":"string"},"period_end":{"format":"date","type":"string"},"period_start":{"description":"Null for instant (balance-sheet) values.","format":"date","type":["string","null"]},"source_url":{"format":"uri","type":"string"},"tag":{"description":"XBRL tag the value was reported under; for a derived metric, the input tags.","type":"string"},"unit":{"description":"Currency or unit as filed, e.g. USD, USD/shares, shares.","type":"string"},"value":{"description":"Exact reported value, serialized without floating-point rounding.","type":"number"}},"required":["value","unit","period_start","period_end","filed","accession","tag","source_url"],"type":"object"},"Parent":{"properties":{"id":{"type":"string"},"name":{"type":"string"},"relationship":{"type":"string"},"source":{"type":"string"},"url":{"type":"string"}},"required":["id","name","relationship","source","url"],"type":"object"},"PriceValuation":{"properties":{"dividend_yield":{"type":["number","null"]},"market_cap":{"type":["number","null"]},"note":{"type":"string"},"pb_ratio":{"type":["number","null"]},"pe_ratio":{"type":["number","null"]},"price":{"type":"number"},"price_as_of":{"type":["string","null"]}},"required":["price","price_as_of","market_cap","pe_ratio","pb_ratio","dividend_yield","note"],"type":"object"},"Profile":{"properties":{"exchange":{"type":["string","null"]},"fiscal_year_end":{"type":["string","null"]},"industry":{"type":["string","null"]},"sector":{"type":["string","null"]},"source":{"type":"string"},"state_of_incorporation":{"type":["string","null"]}},"required":["sector","industry","exchange","state_of_incorporation","fiscal_year_end","source"],"type":"object"},"RefreshStatus":{"properties":{"status":{"description":"ok, degraded or failed when the control plane answers.","type":"string"}},"required":["status"],"type":"object"},"ReviewedPassage":{"properties":{"accounting_series_reconciled":{"type":"boolean"},"captured_at":{"type":"string"},"cik":{"type":"integer"},"end_char":{"type":"integer"},"event_date":{"type":"string"},"id":{"type":"string"},"interpretation":{"type":"string"},"normalized_text_sha256":{"type":"string"},"quote":{"type":"string"},"quote_sha256":{"type":"string"},"section":{"type":"string"},"source_sha256":{"type":"string"},"source_url":{"type":"string"},"start_char":{"type":"integer"},"ticker":{"type":"string"},"title":{"type":"string"},"verification":{"type":"string"},"verified_at":{"type":"string"}},"required":["id","cik","ticker","title","event_date","section","quote","source_url","verified_at"],"type":"object"},"ScreenResult":{"properties":{"applied_filters":{"additionalProperties":{"type":"number"},"description":"Applied leverage ceilings, under their canonical names.","type":"object"},"count":{"minimum":0,"type":"integer"},"definitions":{"additionalProperties":{"type":"string"},"type":"object"},"notice":{"type":"string"},"offset":{"description":"Rows skipped before results.","minimum":0,"type":"integer"},"results":{"items":{"$ref":"#/components/schemas/ScreenRow"},"type":"array"},"sort":{"type":"string"},"source":{"type":"string"},"stale_excluded":{"description":"Matching companies left out because their latest annual report ended over about 18 months ago; pass include_stale=true.","minimum":1,"type":"integer"},"terms":{"format":"uri","type":"string"},"total":{"minimum":0,"type":"integer"},"warnings":{"items":{"type":"string"},"type":"array"}},"required":["notice","terms","total","count","offset","sort","source","results"],"type":"object"},"ScreenRow":{"properties":{"currency":{"type":["string","null"]},"exchange":{"type":["string","null"]},"gross_margin":{"type":"number"},"gross_margin_note":{"type":"string"},"industry":{"type":["string","null"]},"liabilities_to_equity":{"type":["number","null"]},"long_term_debt_to_equity":{"type":["number","null"]},"name":{"type":"string"},"net_income":{"type":"number"},"net_margin":{"type":"number"},"operating_margin":{"type":"number"},"period_end":{"type":["string","null"]},"period_start":{"type":["string","null"]},"period_year":{"type":"integer"},"return_on_equity":{"type":"number"},"revenue":{"type":"number"},"revenue_growth":{"type":"number"},"sector":{"type":"string"},"ticker":{"type":"string"},"total_assets":{"type":"number"}},"required":["ticker","name","period_start","period_end","currency","industry","exchange"],"type":"object"},"Selection":{"properties":{"missing_metrics_by_period":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"},"note":{"description":"Why fewer periods came back than were available.","type":"string"},"periods_returned":{"minimum":0,"type":"integer"},"requested_metrics":{"items":{"type":"string"},"type":"array"},"requested_ratios":{"items":{"type":"string"},"type":"array"},"resolved":{"additionalProperties":{"type":"string"},"description":"Requested spelling to the unambiguous key it was read as, e.g. roe to return_on_equity. Generic debt_to_equity is rejected as ambiguous.","type":"object"}},"required":["periods_returned","requested_metrics","missing_metrics_by_period"],"type":"object"},"Source":{"properties":{"coverage":{"type":"string"},"id":{"type":"string"},"license":{"type":"string"},"license_url":{"type":"string"},"name":{"type":"string"},"retrieved_at":{"type":"string"},"status":{"description":"ok, stale or unavailable.","type":"string"},"url":{"type":"string"}},"required":["id","name","url","license","license_url","retrieved_at","status","coverage"],"type":"object"},"WatchlistSummaries":{"properties":{"built_at":{"type":"string"},"results":{"items":{"required":["requested_ticker"],"type":"object"},"type":"array"}},"required":["results"],"type":"object"}},"securitySchemes":{"bearerKey":{"description":"Optional free API key (tfk_...), emailed from POST /api/v1/keys. Raises the agent-surface rate limit; everything also works without one.","scheme":"bearer","type":"http"}}},"externalDocs":{"description":"Developer and agent guide","url":"https://tickerfacts.com/developers"},"info":{"description":"Data traces to SEC EDGAR filings and named government sources. For research and education only; not financial advice or a recommendation to buy, sell or hold.","license":{"name":"Source data is US government public domain","url":"https://tickerfacts.com/sources"},"summary":"US public-company fundamentals from SEC EDGAR, plus county context and economic series.","termsOfService":"https://tickerfacts.com/terms","title":"TickerFacts JSON API","version":"0.1.0"},"openapi":"3.1.0","paths":{"/api/v1/companies":{"get":{"operationId":"getFundamentalsBatch","parameters":[{"description":"1-20 comma-separated tickers.","in":"query","name":"tickers","required":true,"schema":{"type":"string"}},{"in":"query","name":"periods","schema":{"type":"string"}},{"in":"query","name":"metrics","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyBatch"}}},"description":"Per-ticker results with explicit per-ticker errors."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such record in this build."}},"summary":"Annual fundamentals for 1-20 companies."}},"/api/v1/companies/{ticker}":{"get":{"operationId":"getFundamentals","parameters":[{"description":"US ticker symbol, e.g. AAPL","in":"path","name":"ticker","required":true,"schema":{"type":"string"}},{"description":"Newest annual period groups to return; omitted means all.","in":"query","name":"periods","schema":{"type":"string"}},{"description":"Comma-separated metric or ratio keys (gross_margin, operating_margin, net_margin, return_on_equity, liabilities_to_equity, long_term_debt_to_equity, revenue_growth, or <metric>_growth); omitted means all metrics and ratios.","in":"query","name":"metrics","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}},"description":"Annual observations with units, filing dates and source URLs."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such record in this build."}},"summary":"Annual fundamentals for one company."}},"/api/v1/counties":{"get":{"operationId":"getCountyAtlas","responses":{"200":{"content":{"application/json":{"schema":{"required":["rows","metrics"],"type":"object"}}},"description":"All counties in the compact positional format, with the metric legend. Use /api/v1/counties/{county} for one decoded county."}},"summary":"The complete county atlas artifact (about 5 MB)."}},"/api/v1/counties/{county}":{"get":{"operationId":"getCountyContext","parameters":[{"description":"FIPS code (48453) or name with state (Travis, Texas).","in":"path","name":"county","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CountyContext"},{"$ref":"#/components/schemas/CountyCandidates"}]}}},"description":"Labelled ACS characteristics with 90% margins of error and QCEW industry employment, or a candidate list when the name is ambiguous."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No county matches."}},"summary":"One county, decoded, by FIPS code or name."}},"/api/v1/economy":{"get":{"operationId":"getEconomicContext","parameters":[{"description":"Comma-separated series ids; omitted means all.","in":"query","name":"series","schema":{"type":"string"}},{"description":"First observation date (YYYY, YYYY-MM or YYYY-MM-DD); omitted means the whole history.","in":"query","name":"since","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EconomicContext"}}},"description":"Series with observation dates, units and provenance."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such record in this build."}},"summary":"Treasury yields and BLS inflation, employment and wage series."}},"/api/v1/evidence/{ticker}":{"get":{"operationId":"getCompanyEvidence","parameters":[{"description":"US ticker symbol, e.g. AAPL","in":"path","name":"ticker","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyEvidence"}}},"description":"Reviewed passages; an empty list means none are reviewed for this company, not that no events occurred."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such record in this build."}},"summary":"Reviewed primary-source passages. Selective coverage."}},"/api/v1/feedback":{"post":{"operationId":"sendFeedback","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"agent":{"description":"Your client or agent and version, e.g. \"claude-code 2.1\" or \"acme-research-bot\".","maxLength":200,"type":"string"},"attempted_arguments":{"description":"The arguments of the call that failed or fell short, as JSON text.","maxLength":1000,"type":"string"},"contact":{"description":"An email or URL for follow-up, if the person you work for wants one. Optional; not published.","maxLength":200,"type":"string"},"details":{"description":"Anything else: the figure you expected and its source, the workaround you used, how often this comes up.","maxLength":2000,"type":"string"},"in_reply_to":{"description":"The id of an earlier report you are continuing (from its reply), when answering the questions it asked.","maxLength":200,"type":"string"},"kind":{"description":"missing_data: a company, period, metric or filter you needed is not served. wrong_data: a served figure or label looks incorrect (say which and why). confusing_response: the result or error was hard to use. feature_request: a capability that would help. works_well: what was useful. other.","enum":["missing_data","wrong_data","confusing_response","feature_request","works_well","other"],"type":"string"},"summary":{"description":"One or two sentences: what you needed and what happened. Required.","maxLength":500,"minLength":10,"type":"string"},"ticker":{"description":"The company or companies involved, if any.","maxLength":200,"type":"string"},"tool":{"description":"The tool or endpoint involved, e.g. get_fundamentals or /api/v1/screen.","maxLength":200,"type":"string"},"use_case":{"description":"What your user is trying to accomplish overall (the task, not the call). This is the most useful field.","maxLength":500,"type":"string"},"would_solve_it":{"description":"The exact fields, periods, companies, filters or behaviour that would have solved it.","maxLength":500,"type":"string"}},"required":["kind","summary"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"properties":{"id":{"type":"string"},"kind":{"type":"string"},"message":{"type":"string"},"one_more_thing":{"type":"string"},"received":{"type":"boolean"}},"required":["received","id","kind","message"],"type":"object"}}},"description":"Recorded."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Missing or malformed fields."}},"security":[{}],"summary":"Tell TickerFacts what you needed: missing or wrong data, a confusing response, a feature, or what worked. Same fields as the MCP send_feedback tool."}},"/api/v1/keys":{"post":{"operationId":"requestApiKey","requestBody":{"content":{"application/json":{"schema":{"properties":{"email":{"format":"email","type":"string"}},"required":["email"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}},"required":["status"],"type":"object"}}},"description":"Key sent."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Not a deliverable address."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A key went to this address recently, or this network asked for several."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Issuance is not configured."}},"security":[{}],"summary":"Email a free API key to an address. The key is never returned in the response."}},"/api/v1/refresh":{"get":{"operationId":"getRefreshStatus","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshStatus"}}},"description":"Build id, timings and status (ok, degraded or failed)."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such record in this build."}},"summary":"Nightly build status for this dataset."}},"/api/v1/research/{ticker}":{"get":{"operationId":"getCompanyResearch","parameters":[{"description":"US ticker symbol, e.g. AAPL","in":"path","name":"ticker","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyResearch"}}},"description":"Research record with source licenses and coverage dates."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such record in this build."}},"summary":"Filings, insider disclosures, aliases and legal-entity relationships."}},"/api/v1/screen":{"get":{"operationId":"screenCompanies","parameters":[{"description":"Match ticker prefix, company name, industry or sector.","in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"sector","schema":{"type":"string"}},{"in":"query","name":"industry","schema":{"type":"string"}},{"in":"query","name":"exchange","schema":{"type":"string"}},{"in":"query","name":"currency","schema":{"type":"string"}},{"in":"query","name":"revenue_min","schema":{"type":"number"}},{"in":"query","name":"revenue_max","schema":{"type":"number"}},{"in":"query","name":"net_income_min","schema":{"type":"number"}},{"in":"query","name":"total_assets_min","schema":{"type":"number"}},{"in":"query","name":"gross_margin_min","schema":{"type":"number"}},{"in":"query","name":"operating_margin_min","schema":{"type":"number"}},{"in":"query","name":"net_margin_min","schema":{"type":"number"}},{"in":"query","name":"roe_min","schema":{"type":"number"}},{"in":"query","name":"revenue_growth_min","schema":{"type":"number"}},{"description":"Maximum total liabilities / year-end equity.","in":"query","name":"liabilities_to_equity_max","schema":{"type":"number"}},{"description":"Maximum long-term debt including current maturities / year-end equity; excludes short-term borrowings and leases.","in":"query","name":"long_term_debt_to_equity_max","schema":{"type":"number"}},{"deprecated":true,"description":"Deprecated alias for liabilities_to_equity_max; returns a warning and cannot be combined with the canonical parameter.","in":"query","name":"debt_to_equity_max","schema":{"type":"number"}},{"in":"query","name":"profitable","schema":{"type":"boolean"}},{"description":"Include companies whose latest annual report ended more than about 18 months ago.","in":"query","name":"include_stale","schema":{"type":"boolean"}},{"in":"query","name":"sort","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenResult"}}},"description":"Ranked companies with their key figures and a total count; ignored_parameters lists any parameter the screen does not know."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such record in this build."}},"summary":"Filter companies on latest-period fundamentals."}},"/api/v1/search":{"get":{"operationId":"searchCompanies","parameters":[{"description":"Company name or ticker; q is accepted too.","in":"query","name":"query","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"maximum":25,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearch"}}},"description":"Best matches first, with ticker, CIK, listing status and latest annual period."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such record in this build."}},"summary":"Find companies by name or ticker, forgiving typos."}},"/api/v1/valuation/{ticker}":{"get":{"operationId":"getCashflowInputs","parameters":[{"description":"US ticker symbol, e.g. AAPL","in":"path","name":"ticker","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashflowInputs"}}},"description":"Operating cash flow, capex, net income and share count per period, each with its source filing."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such record in this build."}},"summary":"Dated cash-flow inputs. Observations only: no fair value."}},"/api/v1/watchlist":{"get":{"operationId":"getWatchlistSummaries","parameters":[{"in":"query","name":"tickers","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistSummaries"}}},"description":"One summary row per ticker."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such record in this build."}},"summary":"Annual summaries for up to 50 tickers."}}},"security":[{},{"bearerKey":[]}],"servers":[{"url":"https://tickerfacts.com"}]}