{ "openapi": "3.1.0", "info": { "title": "Finterm API", "version": "1.0.0", "description": "The Finterm financial-data API. Every response is the two-key envelope: `finterm` (the meta header) and `data` (the published result contract), or `finterm` + `error` on failure.\n\n## Error registry\n\n| Code | HTTP | Description | Message |\n| --- | --- | --- | --- |\n| `INVALID_REQUEST` | 400 | The request body failed schema validation, or the tool rejected the parameters as invalid or incomplete. | The request parameters are invalid or incomplete. |\n| `INVALID_JSON` | 400 | The request body was not valid JSON. | The request body was not valid JSON. |\n| `TOKEN_INVALID` | 401 | The bearer token is missing, expired, or not recognized. | The API key is missing, expired, or not recognized. |\n| `SUBSCRIPTION_REQUIRED` | 402 | An active Finterm Pro subscription is required. The envelope carries the machine-readable error.upgrade_url; after checkout there, retrying succeeds automatically. | An active Finterm Pro subscription is required. |\n| `RATE_LIMITED` | 429 | The caller has exceeded the request rate limit; retry later. | Too many requests; retry later. |\n| `RUNTIME_UNAVAILABLE` | 503 | The tool runtime is not available for this deployment. | The service is temporarily unavailable; retry later. |\n| `RUNTIME_QUEUE_FULL` | 429 | The tool runtime queue is full; retry later. | The service is busy; retry later. |\n| `RUNTIME_TOOL_UNAVAILABLE` | 501 | The tool is routed but not yet runnable. | This tool is not yet available. |\n| `RUNTIME_RUN_FAILED` | 502 | The tool runtime reported the run as a non-success terminal state. | The run did not complete successfully. |\n| `RUNTIME_CONTRACT_MISMATCH` | 502 | The tool runtime returned a result that did not match the published contract. | The service returned an unexpected result shape. |\n| `TOOL_EXECUTION_FAILED` | 502 | The tool executed but reported an upstream failure. | The tool ran but could not complete the request. |\n| `UPSTREAM_AUTH` | 502 | A data source rejected the service’s own credentials. A service-side configuration fault, not a caller authentication problem. | A data source could not be accessed due to a service configuration issue. |\n| `UPSTREAM_QUOTA` | 503 | A data source is over its service-side usage limit; retry later. | A data source is temporarily over capacity; retry later. |\n| `UPSTREAM_UNAVAILABLE` | 502 | A data source failed, timed out, or returned an unusable response; retry later. | A data source is temporarily unavailable; retry later. |\n| `BUNDLE_NOT_FOUND` | 404 | No bundle exists with the requested name. | No bundle exists with the requested name. |\n| `RUN_NOT_FOUND` | 404 | No run exists with the requested id for this caller. | No run exists with the requested id. |\n| `MANIFEST_NOT_READY` | 409 | The run has not completed, so the sync manifest is not yet available. | The run has not completed yet. |" }, "servers": [ { "url": "https://api.finterm.ai", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Point Tools", "description": "Single-purpose data tools (one request, one synchronous result)." }, { "name": "Bundle Tools", "description": "Composed multi-section tools served via the run lifecycle." }, { "name": "Account", "description": "The authenticated account/entitlement read (works without Pro)." }, { "name": "Feedback", "description": "Submit bugs, questions, and feature requests (works without Pro)." } ], "paths": { "/api/v1/prices/current": { "post": { "operationId": "stockPricesCurrent", "summary": "Latest available price for one or more stock symbols, delayed by up to 15 minutes.", "description": "Get the latest available price for one or more stock symbols in a single call.\nPrices are the latest available from Finterm’s market-data provider.\nThey are delayed by up to 15 minutes depending on provider plan and exchange\nentitlements.\nReturns one price per requested symbol; historical dates are not supported.", "tags": [ "Point Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbols": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string" }, "description": "Stock ticker symbols to fetch current prices for" } }, "required": [ "symbols" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "description": "One result object for a single requested symbol, or a map keyed by requested symbol when more than one symbol is requested.", "oneOf": [ { "$ref": "#/components/schemas/StockPricesCurrent" }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/StockPricesCurrent" }, "description": "Result objects keyed by requested symbol." } ] } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "Current prices for two symbols.", "source": "finterm tool stock_prices_current NVDA AAPL" } ] } }, "/api/v1/technical-indicators": { "post": { "operationId": "technicalIndicators", "summary": "Standard momentum and trend indicators (RSI, MACD, SMA) for a symbol.", "description": "Calculate standard momentum and trend indicators.\nReturns RSI(14) with conventional above-70 overbought and below-30 oversold heuristic\nlabels; those labels are not reversal forecasts.\nAlso returns MACD for momentum and the 20- and 50-period simple moving averages for\ntrend direction.", "tags": [ "Point Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbols": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string" }, "description": "Stock ticker symbols" }, "date": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$", "description": "Indicator date in YYYY-MM-DD format" } }, "required": [ "symbols", "date" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/TechnicalIndicators" } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "Default indicator set for one symbol.", "source": "finterm tool technical_indicators AAPL --as-of-date 2024-01-16" } ] } }, "/api/v1/sec/search": { "post": { "operationId": "secFilingsSearch", "summary": "Search SEC EDGAR filings for a company by ticker and form type.", "description": "Find a company’s SEC filings by ticker symbol.\nCovers annual reports (10-K, 20-F) and interim reports (10-Q, 6-K). Each result carries\nthe accession number, form type, filing date, company name, document URL, and the fiscal\nyear, fiscal period, and period-end date when available.\nUse the returned fiscal year and period with sec_filing_fetch to pull narrative\nsections.", "tags": [ "Point Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol" }, "form_type": { "description": "SEC form type", "type": "string", "enum": [ "10-K", "10-Q", "20-F", "6-K", "all" ] }, "from_date": { "description": "Start filing date in YYYY-MM-DD format", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "limit": { "description": "Maximum filings to return", "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "ticker" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/SecFilingsSearch" } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "Find recent annual reports for a company.", "source": "finterm tool sec_filings_search AAPL --form-type 10-K --as-of-date 2024-12-31" } ] } }, "/api/v1/sec/fetch": { "post": { "operationId": "secFilingFetch", "summary": "Fetch narrative sections from a company’s SEC filing by fiscal year and period.", "description": "Resolve a single SEC filing by ticker, fiscal year, and fiscal period, then return the\nrequested narrative sections (such as risk factors, MD&A, business, or legal\nproceedings) as plain text.\nSemantic section names map across annual and interim filer forms, so the same request\nworks for a 10-K or a 10-Q.", "tags": [ "Point Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol" }, "year": { "type": "integer", "minimum": 1993, "maximum": 2030, "description": "Fiscal year" }, "period": { "type": "string", "enum": [ "FY", "Q1", "Q2", "Q3", "Q4" ], "description": "Fiscal period" }, "sections": { "type": "string", "description": "Comma-separated section names" }, "format": { "description": "Output format", "type": "string", "enum": [ "text", "html" ] } }, "required": [ "ticker", "year", "period", "sections" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/SecFilingFetch" } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "Fetch annual risk factors and MD&A for a company.", "source": "finterm tool sec_filing_fetch AAPL --year 2024 --period FY --sections risk_factors,mda" } ] } }, "/api/v1/sec/diff": { "post": { "operationId": "secFilingDiff", "summary": "Compare two of a company’s SEC filings and report section-level changes.", "description": "Compare two SEC filings for the same company across fiscal periods and report what\nchanged, section by section.\nReturns a compact per-section manifest (changed, unchanged, or unavailable, with line\ncounts and a prose churn percentage for changed sections) alongside a rendered Markdown\nreport. Summary mode returns the manifest only; diff mode adds the changed hunks.", "tags": [ "Point Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol" }, "base": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 1993, "maximum": 2030, "description": "Fiscal year (for example, 2024)" }, "period": { "type": "string", "enum": [ "FY", "Q1", "Q2", "Q3", "Q4" ], "description": "Fiscal period" } }, "required": [ "year", "period" ], "additionalProperties": false, "description": "Baseline filing" }, "compare": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 1993, "maximum": 2030, "description": "Fiscal year (for example, 2024)" }, "period": { "type": "string", "enum": [ "FY", "Q1", "Q2", "Q3", "Q4" ], "description": "Fiscal period" } }, "required": [ "year", "period" ], "additionalProperties": false, "description": "Comparison filing" }, "sections": { "description": "Comma-separated section names", "type": "string" }, "mode": { "description": "Output mode", "type": "string", "enum": [ "diff", "raw", "summary" ] }, "qa": { "description": "Run the QA fidelity review", "type": "boolean" } }, "required": [ "ticker", "base", "compare" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/SecFilingDiff" } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "Summarize changed risk factors between two annual filings.", "source": "finterm tool sec_filing_diff AAPL --base 2023:FY --compare 2024:FY --sections risk_factors --mode summary" } ] } }, "/api/v1/options/sentiment": { "post": { "operationId": "optionsSentiment", "summary": "Put/call options sentiment for a symbol on a specific date, with a sample-quality verdict.", "description": "Measure options-market sentiment for one underlying symbol on a specific date.\nReturns the put/call volume ratio and its fixed convention label (below 0.7 bullish,\n0.7–1.0 neutral, above 1.0 bearish), call and put volume, the average bid/ask spread,\nand a liquidity grade.\nThe thresholds are descriptive conventions, not calibrated forecasts for a symbol or\nmarket regime. A data_quality block reports whether the sample is solid (\"ok\"), empty\n(\"no_data\", e.g. a non-trading day), or too small to trust (\"thin_sample\"), so a reading\nis never mistaken for a confident one.\nThe date is required and identifies which day to report.", "tags": [ "Point Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "underlying_ticker": { "type": "string", "description": "Underlying stock ticker symbol" }, "date": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$", "description": "Historical options sentiment date in YYYY-MM-DD format" }, "include_spread_analysis": { "description": "Include bid-ask spread analysis", "type": "boolean" }, "expiration_filter": { "description": "Only contracts expiring on/after this date (YYYY-MM-DD)", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "max_contracts": { "description": "Maximum contracts to analyze", "type": "number" } }, "required": [ "underlying_ticker", "date" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/OptionsSentiment" } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "Options sentiment for one symbol on a specific date.", "source": "finterm tool options_sentiment AAPL --as-of-date 2024-01-15" } ] } }, "/api/v1/options/overview": { "post": { "operationId": "optionsOverview", "summary": "A live one-call options overview: implied vs realized volatility with rank, today's flow, the positioning book, expected moves, and probability bands.", "description": "Get a live one-call options overview for a ticker.\nOne full-chain snapshot is summarized into a volatility block (30-day implied vs 20-day\nrealized vol, their spread, skew, and the rank/percentile of today’s IV in the ticker’s\nown year), a flow block (today’s volume with put/call splits and reference averages),\nand a positioning block (open interest, max pain, and the largest open-interest\nstrikes). It adds expected moves per expiry (always including the first expiry on or\nafter the next earnings date), lognormal probability bands, quotable derived[]\nsentences, condition flags, and a data_quality block.\nHistory-dependent fields report null with a days-collected count while the daily series\nfills, never fabricated.\nServes live data only; pass a past date to options_sentiment instead.", "tags": [ "Point Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol" }, "as_of_date": { "description": "As-of date: 'today' or YYYY-MM-DD", "type": "string", "pattern": "^(today|\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01]))$" } }, "required": [ "ticker" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/OptionsOverview" } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "Live options overview for one symbol.", "source": "finterm tool options_overview TSLA" } ] } }, "/api/v1/fundamentals/financials": { "post": { "operationId": "financialStatements", "summary": "Reported balance sheet, income statement, or cash flow for a company.", "description": "Get a company’s reported financial statements (balance sheet, income statement, or cash\nflow), one statement type per call, as a series of reporting periods.\nUse it to analyze financial health, profitability, and cash generation.\nEach period carries its fiscal year and quarter, the period end and filing dates, and\nthe statement’s line items.", "tags": [ "Point Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol" }, "statement_type": { "type": "string", "enum": [ "balance_sheet", "income_statement", "cash_flow" ], "description": "Financial statement type" }, "as_of_date": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$", "description": "Filing-date cutoff in YYYY-MM-DD format" }, "timeframe": { "description": "Period type", "type": "string", "enum": [ "quarterly", "annual", "trailing_twelve_months" ] }, "fiscal_year": { "description": "Fiscal-year filter", "type": "number" }, "fiscal_quarter": { "description": "Fiscal-quarter filter", "type": "number", "minimum": 1, "maximum": 4 }, "limit": { "description": "Number of periods to return", "type": "number", "minimum": 1, "maximum": 20 } }, "required": [ "ticker", "statement_type", "as_of_date" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/FinancialStatements" } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "The last four quarterly income statements.", "source": "finterm tool financial_statements AAPL --statement-type income_statement --as-of-date 2024-12-01 --timeframe quarterly" } ] } }, "/api/v1/ownership/insider-trades": { "post": { "operationId": "insiderTrades", "summary": "SEC Form 4 insider transactions with a trailing 90-day open-market summary.", "description": "Get insider transactions and holdings filed with the SEC by a company’s officers,\ndirectors, and 10% owners, normalized into one row per reported security event.\nEach row carries the owner’s role flags, the transaction code and type, shares, price,\nvalue, post-transaction ownership, whether it was part of a pre-arranged trading plan,\nand the source filing URL. A summary block reports the trailing 90-day open-market net\nvalue with buy and sell counts, and whether that window was fully scanned.\nPass a date to get the view as of a specific filing date.", "tags": [ "Point Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol" }, "as_of_date": { "description": "Filing-date cutoff in YYYY-MM-DD format", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "limit": { "description": "Maximum rows to return", "type": "integer", "minimum": 1, "maximum": 500 }, "transaction_codes": { "description": "Form 4 transaction-code filters", "type": "array", "items": { "type": "string", "enum": [ "P", "S", "A", "M", "F", "G", "C", "W" ] } }, "include_derivatives": { "description": "Include derivative-security rows", "type": "boolean" }, "include_holdings": { "description": "Include ownership-statement rows", "type": "boolean" } }, "required": [ "ticker" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/InsiderTrades" } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "Recent insider transactions for one symbol.", "source": "finterm tool insider_trades AAPL --as-of-date 2024-03-15" } ] } }, "/api/v1/ownership/institutional-holdings": { "post": { "operationId": "institutionalHoldings", "summary": "SEC Form 13F institutional holders for a stock or the portfolio of one manager.", "description": "Get institutional ownership from SEC Form 13F filings in either of two modes.\nIn ticker mode, pass a symbol to list the institutional managers that hold that\nsecurity, ranked by reported value across the scanned filing window.\nIn investor mode, pass a manager’s SEC CIK to list the positions in that manager’s\nlatest filing, ranked by value.\nEach row carries the filer, the period and filing dates, the security and its CUSIP,\nshares and reported value, voting authority, and whether the row is from a stale\n(superseded) filing.", "tags": [ "Point Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "description": "Ticker holder mode", "type": "string" }, "investor_cik": { "description": "Investor portfolio mode SEC CIK", "type": "string" }, "as_of_date": { "description": "Filing-date cutoff in YYYY-MM-DD format", "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "limit": { "description": "Maximum rows to return", "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/InstitutionalHoldings" } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "Institutional holders of one symbol.", "source": "finterm tool institutional_holdings AAPL --as-of-date 2024-03-15" } ] } }, "/api/v1/ticker-sentiment": { "post": { "operationId": "tickerSentiment", "summary": "A live 0-100 sentiment composite for a ticker: seven components scored vs the ticker's own year, grouped trend / flow / positioning.", "description": "Get a live 0-100 sentiment score for a ticker, composed of seven components grouped into\ntrend, flow, and positioning sub-scores.\nEach component is scored as a percentile vs the ticker’s own trailing year and oriented\nso 100 is the greed side.\nThe result carries the composite score with a band label (extreme fear to extreme greed;\ncutoffs versioned in the methodology block), the three sub-scores, every component with\nits raw value, percentile, and window, deltas over 1, 5, and 20 trading days, a weekly\nhistory series, transition flags, and quotable derived[] sentences.\nA thin option chain degrades to a disclosed coverage with omission reasons, so the score\nnever silently changes meaning.\nServes live data only.", "tags": [ "Point Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol" }, "as_of_date": { "description": "As-of date: 'today' or YYYY-MM-DD", "type": "string", "pattern": "^(today|\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01]))$" } }, "required": [ "ticker" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/TickerSentiment" } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "Live sentiment composite for one symbol.", "source": "finterm tool ticker_sentiment AAPL" } ] } }, "/api/v1/bundles/ticker_data/runs": { "post": { "operationId": "runTickerDataBundle", "summary": "The full ticker snapshot: earnings, guidance, the price reaction window, ratios, options sentiment, short pressure, technicals, financial statements, and pre-earnings market context, in one call.", "description": "Get the complete data snapshot for a ticker in a single bundle run.\nticker_data composes finterm’s individual data tools into one bundle anchored on a\ncompany’s most recent earnings event, so you can read the whole picture without\nstitching ten separate requests together.\nEach section is self-contained and is present only when it has data; a section that\nproduced nothing comes back as null.\n\nThe bundle returns:\n\n- **earnings:** the reported quarter’s actuals, estimates, and surprise for both EPS and\n revenue, with the fiscal quarter.\n- **guidance:** forward guidance for the period being analyzed: the revenue and EPS\n ranges (min / max / mid, plus the prior range and whether the guide was revised).\n- **prices:** the event-study price window around the earnings close: the prior trading\n day, the event close, and the closes one and five trading days later.\n- **ratios:** trailing-twelve-month margins, return on equity, and the P/E ratio.\n- **options:** put/call sentiment with its interpretation, call and put volume, the\n average spread, a liquidity grade, and a data-quality verdict so a thin sample is\n never mistaken for a confident reading.\n- **short:** short interest (shares short, days to cover) and recent short-volume\n pressure.\n- **technical_indicators:** the default set: RSI(14), MACD(12/26/9), and the 20- and\n 50-period simple moving averages.\n- **financial_statements:** a key-metric snapshot by default, or the full income\n statement, balance sheet, and cash flow on request.\n- **pre_earnings_context:** the stock’s run-up into the event, where its price sits in\n its 52-week range, a volatility proxy, and the index versus its 200-day average.\n\nEach external CLI invocation creates a bundle run for one ticker; create another run for\nanother ticker.", "tags": [ "Bundle Tools" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticker": { "description": "Stock ticker symbol", "type": "string", "minLength": 1 }, "company_name": { "description": "Company name", "type": "string", "minLength": 1 }, "mode": { "description": "Requested execution mode", "type": "string", "enum": [ "placeholder", "live" ] }, "delivery_mode": { "description": "Requested result delivery mode", "type": "string", "enum": [ "inline_result", "artifact_metadata", "summary_json", "dataroom_sync" ] }, "parameters": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Additional bundle parameters" } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Run accepted.", "content": { "application/json": { "schema": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/BundleRun" } }, "required": [ "finterm", "data" ] } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Error (SUBSCRIPTION_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Error (BUNDLE_NOT_FOUND, RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Error (MANIFEST_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED, RUNTIME_QUEUE_FULL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "501": { "description": "Error (RUNTIME_TOOL_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Error (RUNTIME_RUN_FAILED, RUNTIME_CONTRACT_MISMATCH, TOOL_EXECUTION_FAILED, UPSTREAM_AUTH, UPSTREAM_UNAVAILABLE).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Error (RUNTIME_UNAVAILABLE, UPSTREAM_QUOTA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-codeSamples": [ { "lang": "bash", "label": "The full data bundle for one ticker.", "source": "finterm bundle run ticker_data AAPL" }, { "lang": "bash", "label": "Include the full reported financial statements.", "source": "finterm bundle run ticker_data AAPL --param verbose_statements=true" } ] } }, "/api/v1/runs/{runId}": { "get": { "operationId": "getBundleRun", "summary": "Get bundle run status", "description": "Poll a bundle run started via a bundle `…/runs` operation. Append `/result`, `/artifacts`, or `/sync-manifest` to fetch the completed payload.", "tags": [ "Bundle Tools" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The run id returned by the bundle run operation." } ], "responses": { "200": { "description": "The run status envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "404": { "description": "Error (RUN_NOT_FOUND).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/account": { "get": { "operationId": "getAccount", "summary": "Get account and plan state", "description": "The authenticated whoami/entitlement read: the account email and plan/trial state for the calling token. Requires a live bearer token but NOT a Pro subscription; a free account gets 200 with its plan state and the upgrade URL. Never returns token material.", "tags": [ "Account" ], "responses": { "200": { "description": "The account envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountEnvelope" } } } }, "401": { "description": "Error (TOKEN_MISSING, TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/feedback": { "post": { "operationId": "submitFeedback", "summary": "Submit product feedback", "description": "Report a bug, ask a question, or request a feature, straight from the API or the `finterm feedback` CLI command. Requires a live bearer token but NOT a Pro subscription. The body is validated strictly: unknown top-level or context keys are rejected with `INVALID_REQUEST` so the contract is self-teaching. Include `request_ids` from failing responses when reporting a bug; they let the report be correlated with server-side logs.", "tags": [ "Feedback" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackSubmission" } } } }, "responses": { "200": { "description": "Submission received.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackAckEnvelope" } } } }, "400": { "description": "Error (INVALID_REQUEST, INVALID_JSON).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Error (TOKEN_MISSING, TOKEN_INVALID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Error (RATE_LIMITED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A live account API key from `FINTERM_API_KEY`." } }, "schemas": { "Account": { "type": "object", "description": "The calling account and its plan/entitlement state.", "properties": { "email": { "anyOf": [ { "type": "string", "description": "The account email." }, { "type": "null" } ] }, "plan": { "type": "string", "enum": [ "pro", "free" ], "description": "The resolved plan level." }, "has_pro": { "type": "boolean", "description": "Whether the account is entitled to the paid API surface." }, "subscription_status": { "anyOf": [ { "type": "string", "description": "The raw subscription status (active | trialing | past_due | canceled | incomplete | unpaid), or null with no subscription." }, { "type": "null" } ] }, "trial_ends_at": { "anyOf": [ { "type": "number", "description": "Epoch ms the trial ends, when the subscription is trialing." }, { "type": "null" } ] }, "current_period_end": { "anyOf": [ { "type": "number", "description": "Epoch ms the current paid period ends, or null when not subscribed." }, { "type": "null" } ] }, "cancel_at_period_end": { "type": "boolean", "description": "Whether the subscription is set to cancel at period end." }, "upgrade_url": { "type": "string", "description": "The upgrade/conversion URL, present only when the account is not entitled." } }, "required": [ "email", "plan", "has_pro", "subscription_status", "trial_ends_at", "current_period_end", "cancel_at_period_end" ] }, "AccountEnvelope": { "type": "object", "description": "The two-key success envelope carrying the account state.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/Account" } }, "required": [ "finterm", "data" ] }, "BundleRun": { "type": "object", "description": "The asynchronous bundle run state returned when a bundle run is accepted.", "properties": { "run_id": { "type": "string", "description": "Stable bundle run id." }, "bundle_name": { "type": "string", "description": "The bundle name." }, "descriptor_id": { "type": "string", "description": "The bundle descriptor id." }, "lifecycle": { "type": "string", "enum": [ "mock_runtime", "runtime_http" ], "description": "The run lifecycle implementation." }, "runtime_adapter": { "type": "string", "enum": [ "mock", "http" ], "description": "The runtime adapter handling this run." }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "expired" ], "description": "The current run status." }, "state": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "expired" ], "description": "Alias of the current run status." }, "normalized_request": { "type": "object", "additionalProperties": true, "description": "The normalized public request for the run." }, "submitted_at": { "type": "string", "description": "Run submission timestamp." }, "started_at": { "anyOf": [ { "type": "string", "description": "Run start timestamp, if the run has started." }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "Run completion timestamp, if the run has finished." }, { "type": "null" } ] }, "updated_at": { "type": "string", "description": "Last run update timestamp." }, "result": { "anyOf": [ { "type": "object", "additionalProperties": true, "description": "Run result metadata when available." }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "additionalProperties": true, "description": "Run error metadata when available." }, { "type": "null" } ] }, "runtime_acknowledged": { "type": "boolean", "description": "Whether the runtime acknowledged the run." }, "manifest_ready": { "type": "boolean", "description": "Whether the run sync manifest is available." }, "links": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Lifecycle URLs for this run." } }, "required": [ "run_id", "bundle_name", "descriptor_id", "lifecycle", "runtime_adapter", "status", "state", "normalized_request", "submitted_at", "started_at", "completed_at", "updated_at", "result", "error", "runtime_acknowledged", "manifest_ready", "links" ] }, "ErrorEnvelope": { "type": "object", "description": "The two-key error envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable public error code." }, "message": { "type": "string", "description": "Human-readable, external-clean message." }, "upgrade_url": { "type": "string", "description": "Machine-readable upgrade URL, present only on SUBSCRIPTION_REQUIRED (402): complete checkout there, then retry; access activates automatically." } }, "required": [ "code", "message" ] } }, "required": [ "finterm", "error" ] }, "FeedbackAck": { "type": "object", "description": "Acknowledgement that a feedback submission was received.", "properties": { "feedback_id": { "type": "string", "description": "Stable id of the stored submission." }, "status": { "type": "string", "enum": [ "received" ], "description": "Always `received` on success." } }, "required": [ "feedback_id", "status" ] }, "FeedbackAckEnvelope": { "type": "object", "description": "The two-key success envelope carrying the feedback acknowledgement.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "$ref": "#/components/schemas/FeedbackAck" } }, "required": [ "finterm", "data" ] }, "FeedbackSubmission": { "type": "object", "description": "A bug report, question, or feature request.", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "bug", "question", "feature_request" ], "description": "What kind of feedback this is." }, "summary": { "type": "string", "minLength": 1, "maxLength": 200, "description": "One-line summary of the report (at most 200 characters; no newlines or control characters)." }, "submission_id": { "type": "string", "minLength": 8, "maxLength": 64, "description": "Client-generated idempotency key, one per user-approved submission (a UUID works). Retrying with the same id returns the original acknowledgement instead of storing a duplicate report." }, "body": { "type": "string", "maxLength": 16384, "description": "Optional Markdown detail (at most 16 KB): what happened, expected vs. actual, reproduction steps." }, "context": { "type": "object", "additionalProperties": false, "description": "Optional structured context. Only the keys documented here are accepted; unknown keys are rejected.", "properties": { "cli_version": { "type": "string", "minLength": 1, "maxLength": 400, "description": "Reporting CLI version." }, "platform": { "type": "string", "minLength": 1, "maxLength": 400, "description": "Reporting OS/architecture." }, "command": { "type": "string", "minLength": 1, "maxLength": 400, "description": "The command line that hit the issue." }, "tool_id": { "type": "string", "minLength": 1, "maxLength": 400, "description": "The snake_case tool id involved." }, "error_code": { "type": "string", "minLength": 1, "maxLength": 400, "description": "The public error code received." }, "request_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 8, "description": "Up to 8 request_id values from affected responses, so a report can be correlated with server-side logs." } } } }, "required": [ "kind", "summary", "submission_id" ] }, "FinancialStatements": { "type": "object", "properties": { "ticker": { "type": "string" }, "statement_type": { "type": "string", "enum": [ "balance_sheet", "income_statement", "cash_flow" ] }, "periods": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "fiscal_year": { "type": "number" }, "fiscal_quarter": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "period_end": { "type": "string" }, "filing_date": { "type": "string" }, "timeframe": { "type": "string" }, "total_assets": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_current_assets": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cash_and_equivalents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "short_term_investments": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "accounts_receivable": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "inventory": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_non_current_assets": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "property_plant_equipment": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "goodwill": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "intangible_assets": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_liabilities": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_current_liabilities": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "accounts_payable": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "short_term_debt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_non_current_liabilities": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "long_term_debt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_equity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "retained_earnings": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "common_stock": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "fiscal_year", "fiscal_quarter", "period_end", "filing_date", "timeframe", "total_assets", "total_current_assets", "cash_and_equivalents", "short_term_investments", "accounts_receivable", "inventory", "total_non_current_assets", "property_plant_equipment", "goodwill", "intangible_assets", "total_liabilities", "total_current_liabilities", "accounts_payable", "short_term_debt", "total_non_current_liabilities", "long_term_debt", "total_equity", "retained_earnings", "common_stock" ], "additionalProperties": false }, { "type": "object", "properties": { "fiscal_year": { "type": "number" }, "fiscal_quarter": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "period_end": { "type": "string" }, "filing_date": { "type": "string" }, "timeframe": { "type": "string" }, "total_revenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cost_of_revenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "gross_profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "operating_expenses": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "operating_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "research_and_development": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "selling_general_admin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "interest_expense": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "interest_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "other_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "income_before_tax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "income_tax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "net_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "earnings_per_share": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "earnings_per_share_diluted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shares_outstanding": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shares_outstanding_diluted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "fiscal_year", "fiscal_quarter", "period_end", "filing_date", "timeframe", "total_revenue", "cost_of_revenue", "gross_profit", "operating_expenses", "operating_income", "research_and_development", "selling_general_admin", "interest_expense", "interest_income", "other_income", "income_before_tax", "income_tax", "net_income", "earnings_per_share", "earnings_per_share_diluted", "shares_outstanding", "shares_outstanding_diluted" ], "additionalProperties": false }, { "type": "object", "properties": { "fiscal_year": { "type": "number" }, "fiscal_quarter": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "period_end": { "type": "string" }, "filing_date": { "type": "string" }, "timeframe": { "type": "string" }, "net_cash_from_operating": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "depreciation_amortization": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "stock_based_compensation": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "change_in_working_capital": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "net_cash_from_investing": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "capital_expenditures": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "acquisitions": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "investment_purchases": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "investment_sales": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "net_cash_from_financing": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "dividends_paid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "share_repurchases": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "debt_issuance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "debt_repayment": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "net_change_in_cash": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "free_cash_flow": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "fiscal_year", "fiscal_quarter", "period_end", "filing_date", "timeframe", "net_cash_from_operating", "depreciation_amortization", "stock_based_compensation", "change_in_working_capital", "net_cash_from_investing", "capital_expenditures", "acquisitions", "investment_purchases", "investment_sales", "net_cash_from_financing", "dividends_paid", "share_repurchases", "debt_issuance", "debt_repayment", "net_change_in_cash", "free_cash_flow" ], "additionalProperties": false } ] } } }, "required": [ "ticker", "statement_type", "periods" ], "additionalProperties": false }, "FintermMeta": { "type": "object", "description": "Canonical result meta header.", "properties": { "schema": { "type": "string", "description": "The published result contract id." }, "tool": { "type": "string", "description": "The snake_case tool id." }, "args": { "type": "object", "additionalProperties": true, "description": "The arguments the caller requested." }, "request_id": { "type": "string", "description": "Server-set, ephemeral request id." }, "cursor": { "type": "string", "description": "Opaque pagination cursor (feed tools only)." } }, "required": [ "schema", "tool", "args" ] }, "InsiderTrades": { "type": "object", "properties": { "ticker": { "type": "string" }, "as_of_date": { "type": "string" }, "trades": { "type": "array", "items": { "type": "object", "properties": { "ticker": { "type": "string" }, "issuer": { "type": "string" }, "name": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_board_director": { "type": "boolean" }, "is_officer": { "type": "boolean" }, "is_ten_percent_owner": { "type": "boolean" }, "record_type": { "type": "string", "enum": [ "transaction", "holding" ] }, "transaction_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filing_date": { "type": "string" }, "transaction_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transaction_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "acquired_disposed": { "anyOf": [ { "type": "string", "enum": [ "A", "D" ] }, { "type": "null" } ] }, "transaction_shares": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "transaction_price_per_share": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "transaction_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shares_owned_after_transaction": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "direct_or_indirect": { "anyOf": [ { "type": "string", "enum": [ "D", "I" ] }, { "type": "null" } ] }, "nature_of_ownership": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "security_title": { "type": "string" }, "security_type": { "type": "string", "enum": [ "non_derivative", "derivative" ] }, "is_10b5_1_plan": { "type": "boolean" }, "filing_url": { "type": "string" } }, "required": [ "ticker", "issuer", "name", "title", "is_board_director", "is_officer", "is_ten_percent_owner", "record_type", "transaction_date", "filing_date", "transaction_code", "transaction_type", "acquired_disposed", "transaction_shares", "transaction_price_per_share", "transaction_value", "shares_owned_after_transaction", "direct_or_indirect", "nature_of_ownership", "security_title", "security_type", "is_10b5_1_plan", "filing_url" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "open_market_net_value_90d": { "type": "number" }, "buy_count_90d": { "type": "number" }, "sell_count_90d": { "type": "number" }, "window_complete": { "type": "boolean" } }, "required": [ "open_market_net_value_90d", "buy_count_90d", "sell_count_90d", "window_complete" ], "additionalProperties": false }, "truncated": { "type": "boolean" } }, "required": [ "ticker", "as_of_date", "trades", "summary", "truncated" ], "additionalProperties": false }, "InstitutionalHoldings": { "type": "object", "properties": { "ticker": { "type": "string" }, "investor_cik": { "type": "string" }, "as_of_date": { "type": "string" }, "latest_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "holders": { "type": "array", "items": { "type": "object", "properties": { "filer_name": { "type": "string" }, "filer_cik": { "type": "string" }, "period_of_report": { "type": "string" }, "filed_at": { "type": "string" }, "form_type": { "type": "string" }, "accession_number": { "type": "string" }, "name_of_issuer": { "type": "string" }, "cusip": { "type": "string" }, "ticker": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title_of_class": { "type": "string" }, "put_call": { "anyOf": [ { "type": "string", "enum": [ "put", "call" ] }, { "type": "null" } ] }, "shares": { "type": "number" }, "shares_type": { "type": "string" }, "value_usd": { "type": "number" }, "investment_discretion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voting_authority_sole": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "voting_authority_shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "voting_authority_none": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "is_stale": { "type": "boolean" }, "filing_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "filer_name", "filer_cik", "period_of_report", "filed_at", "form_type", "accession_number", "name_of_issuer", "cusip", "ticker", "title_of_class", "put_call", "shares", "shares_type", "value_usd", "investment_discretion", "voting_authority_sole", "voting_authority_shared", "voting_authority_none", "is_stale", "filing_url" ], "additionalProperties": false } }, "positions": { "type": "array", "items": { "type": "object", "properties": { "filer_name": { "type": "string" }, "filer_cik": { "type": "string" }, "period_of_report": { "type": "string" }, "filed_at": { "type": "string" }, "form_type": { "type": "string" }, "accession_number": { "type": "string" }, "name_of_issuer": { "type": "string" }, "cusip": { "type": "string" }, "ticker": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title_of_class": { "type": "string" }, "put_call": { "anyOf": [ { "type": "string", "enum": [ "put", "call" ] }, { "type": "null" } ] }, "shares": { "type": "number" }, "shares_type": { "type": "string" }, "value_usd": { "type": "number" }, "investment_discretion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voting_authority_sole": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "voting_authority_shared": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "voting_authority_none": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "is_stale": { "type": "boolean" }, "filing_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "filer_name", "filer_cik", "period_of_report", "filed_at", "form_type", "accession_number", "name_of_issuer", "cusip", "ticker", "title_of_class", "put_call", "shares", "shares_type", "value_usd", "investment_discretion", "voting_authority_sole", "voting_authority_shared", "voting_authority_none", "is_stale", "filing_url" ], "additionalProperties": false } }, "scanned_filings": { "type": "number" }, "scanned_filed_range": { "type": "object", "properties": { "earliest": { "type": "string" }, "latest": { "type": "string" } }, "required": [ "earliest", "latest" ], "additionalProperties": false }, "truncated": { "type": "boolean" } }, "required": [ "as_of_date", "latest_period", "truncated" ], "additionalProperties": false }, "OptionsOverview": { "type": "object", "properties": { "ticker": { "type": "string" }, "as_of_date": { "type": "string" }, "spot": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "context": { "type": "object", "properties": { "next_earnings": { "anyOf": [ { "type": "object", "properties": { "date": { "type": "string" }, "days": { "type": "number" }, "confirmed": { "type": "boolean" } }, "required": [ "date", "days", "confirmed" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "next_earnings" ], "additionalProperties": false }, "volatility": { "type": "object", "properties": { "iv_30": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "hv_20": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "iv_vs_hv": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "skew": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "iv_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "iv_percentile": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "iv_1y_low": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "number" }, "date": { "type": "string" } }, "required": [ "value", "date" ], "additionalProperties": false }, { "type": "null" } ] }, "iv_1y_high": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "number" }, "date": { "type": "string" } }, "required": [ "value", "date" ], "additionalProperties": false }, { "type": "null" } ] }, "hv_rank": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "iv_30", "hv_20", "iv_vs_hv", "skew", "iv_rank", "iv_percentile", "iv_1y_low", "iv_1y_high", "hv_rank" ], "additionalProperties": false }, "flow": { "type": "object", "properties": { "volume": { "type": "number" }, "puts": { "type": "number" }, "calls": { "type": "number" }, "pc_ratio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vs_avg_30d": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pc_5d_avg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pc_percentile_1y": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "volume", "puts", "calls", "pc_ratio", "vs_avg_30d", "pc_5d_avg", "pc_percentile_1y" ], "additionalProperties": false }, "positioning": { "type": "object", "properties": { "open_interest": { "type": "number" }, "puts": { "type": "number" }, "calls": { "type": "number" }, "pc_ratio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vs_avg_30d": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_pain": { "anyOf": [ { "type": "object", "properties": { "strike": { "type": "number" }, "expiry": { "type": "string" }, "spot_vs": { "type": "number" } }, "required": [ "strike", "expiry", "spot_vs" ], "additionalProperties": false }, { "type": "null" } ] }, "top_strikes": { "type": "object", "properties": { "calls": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ] } }, "puts": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" } ] } } }, "required": [ "calls", "puts" ], "additionalProperties": false } }, "required": [ "open_interest", "puts", "calls", "pc_ratio", "vs_avg_30d", "max_pain", "top_strikes" ], "additionalProperties": false }, "expected_move": { "type": "array", "items": { "type": "object", "properties": { "expiry": { "type": "string" }, "days": { "type": "number" }, "pct": { "type": "number" }, "dollars": { "type": "number" }, "post_earnings": { "type": "boolean", "const": true } }, "required": [ "expiry", "days", "pct", "dollars" ], "additionalProperties": false } }, "probability": { "anyOf": [ { "type": "object", "properties": { "expiry": { "type": "string" }, "method": { "type": "string", "const": "lognormal_iv30" }, "bands": { "type": "object", "properties": { "p10": { "type": "number" }, "p25": { "type": "number" }, "p50": { "type": "number" }, "p75": { "type": "number" }, "p90": { "type": "number" } }, "required": [ "p10", "p25", "p50", "p75", "p90" ], "additionalProperties": false } }, "required": [ "expiry", "method", "bands" ], "additionalProperties": false }, { "type": "null" } ] }, "derived": { "type": "array", "items": { "type": "string" } }, "flags": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "object", "properties": { "selection": { "type": "string", "enum": [ "full_chain", "partial_chain" ] }, "contracts_analyzed": { "type": "number" }, "expirations_covered": { "type": "number" }, "pages_fetched": { "type": "number" } }, "required": [ "selection", "contracts_analyzed", "expirations_covered", "pages_fetched" ], "additionalProperties": false }, "data_quality": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "thin", "no_data" ] }, "history": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "accumulating" ] }, "days_collected": { "type": "number" } }, "required": [ "status", "days_collected" ], "additionalProperties": false }, "note": { "type": "string" } }, "required": [ "status", "history" ], "additionalProperties": false }, "methodology": { "type": "object", "properties": { "version": { "type": "string" }, "iv_30": { "type": "string" }, "hv_20": { "type": "string" }, "skew": { "type": "string" }, "expected_move": { "type": "string" }, "probability_bands": { "type": "string" }, "max_pain": { "type": "string" }, "flag_thresholds": { "type": "string" } }, "required": [ "version", "iv_30", "hv_20", "skew", "expected_move", "probability_bands", "max_pain", "flag_thresholds" ], "additionalProperties": false } }, "required": [ "ticker", "as_of_date", "spot", "context", "volatility", "flow", "positioning", "expected_move", "probability", "derived", "flags", "scope", "data_quality", "methodology" ], "additionalProperties": false }, "OptionsSentiment": { "type": "object", "properties": { "ticker": { "type": "string" }, "as_of_date": { "type": "string" }, "sentiment": { "type": "object", "properties": { "put_call_volume_ratio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "interpretation": { "anyOf": [ { "type": "string", "enum": [ "bullish", "neutral", "bearish" ] }, { "type": "null" } ] }, "total_call_volume": { "type": "number" }, "total_put_volume": { "type": "number" }, "avg_spread_percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "liquidity_grade": { "anyOf": [ { "type": "string", "enum": [ "A", "B", "C", "D" ] }, { "type": "null" } ] } }, "required": [ "put_call_volume_ratio", "interpretation", "total_call_volume", "total_put_volume", "avg_spread_percent", "liquidity_grade" ], "additionalProperties": false }, "data_quality": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "no_data", "thin_sample" ] }, "contracts_analyzed": { "type": "number" }, "contracts_with_volume": { "type": "number" }, "total_volume": { "type": "number" } }, "required": [ "status", "contracts_analyzed", "contracts_with_volume", "total_volume" ], "additionalProperties": false }, "contracts": { "type": "object", "properties": { "total_calls": { "type": "number" }, "total_puts": { "type": "number" }, "contracts_with_volume": { "type": "number" }, "expirations": { "type": "array", "items": { "type": "string" } } }, "required": [ "total_calls", "total_puts", "contracts_with_volume", "expirations" ], "additionalProperties": false } }, "required": [ "ticker", "as_of_date", "sentiment", "data_quality", "contracts" ], "additionalProperties": false }, "SecFilingDiff": { "type": "object", "properties": { "ticker": { "type": "string" }, "base": { "type": "object", "properties": { "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "period": { "type": "string" }, "form_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "period_of_report": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "year", "period", "form_type", "filed_at", "period_of_report" ], "additionalProperties": false }, "compare": { "type": "object", "properties": { "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "period": { "type": "string" }, "form_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "period_of_report": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "year", "period", "form_type", "filed_at", "period_of_report" ], "additionalProperties": false }, "mode": { "type": "string", "enum": [ "diff", "raw", "summary" ] }, "manifest": { "type": "array", "items": { "type": "object", "properties": { "section": { "type": "string" }, "status": { "type": "string", "enum": [ "changed", "unchanged", "returned_raw", "unavailable", "error" ] }, "added": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "removed": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "churn_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "section", "status", "added", "removed", "churn_pct", "note" ], "additionalProperties": false } }, "report": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "ticker", "base", "compare", "mode", "manifest", "report" ], "additionalProperties": false }, "SecFilingFetch": { "type": "object", "properties": { "ticker": { "type": "string" }, "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "period": { "type": "string" }, "form_type": { "type": "string" }, "filed_at": { "type": "string" }, "period_of_report": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accession_number": { "type": "string" }, "company_name": { "type": "string" }, "filing_url": { "type": "string" }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "ticker", "year", "period", "form_type", "filed_at", "period_of_report", "accession_number", "company_name", "filing_url", "sections" ], "additionalProperties": false }, "SecFilingsSearch": { "type": "object", "properties": { "total_results": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "filings": { "type": "array", "items": { "type": "object", "properties": { "accession_number": { "type": "string" }, "form_type": { "type": "string" }, "filed_at": { "type": "string" }, "company_name": { "type": "string" }, "filing_url": { "type": "string" }, "period_of_report": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fiscal_year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "fiscal_period": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "accession_number", "form_type", "filed_at", "company_name", "filing_url", "period_of_report", "fiscal_year", "fiscal_period" ], "additionalProperties": false } } }, "required": [ "total_results", "filings" ], "additionalProperties": false }, "StockPricesCurrent": { "type": "object", "properties": { "ticker": { "type": "string" }, "price": { "type": "number" } }, "required": [ "ticker", "price" ], "additionalProperties": false }, "SuccessEnvelope": { "type": "object", "description": "The two-key success envelope.", "properties": { "finterm": { "$ref": "#/components/schemas/FintermMeta" }, "data": { "type": "object", "additionalProperties": true, "description": "The result payload." } }, "required": [ "finterm", "data" ] }, "TechnicalIndicators": { "type": "object", "properties": { "ticker": { "type": "string" }, "rsi_14": { "type": "number" }, "macd_value": { "type": "number" }, "macd_signal": { "type": "number" }, "macd_histogram": { "type": "number" }, "sma_20": { "type": "number" }, "sma_50": { "type": "number" } }, "required": [ "ticker", "rsi_14", "macd_value", "macd_signal", "macd_histogram", "sma_20", "sma_50" ], "additionalProperties": false }, "TickerDataBundle": { "type": "object", "properties": { "ticker": { "type": "string" }, "earnings_date": { "type": "string" }, "earnings": { "anyOf": [ { "type": "object", "properties": { "eps_actual": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "eps_estimate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "eps_surprise_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revenue_actual": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revenue_estimate": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revenue_surprise_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fiscal_quarter": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reported_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "eps_actual", "eps_estimate", "eps_surprise_pct", "revenue_actual", "revenue_estimate", "revenue_surprise_pct", "fiscal_quarter", "reported_at" ], "additionalProperties": false }, { "type": "null" } ] }, "guidance": { "anyOf": [ { "type": "object", "properties": { "fiscal_period": { "type": "string" }, "guidance_date": { "type": "string" }, "revenue_min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revenue_max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revenue_mid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revenue_prev_min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revenue_prev_max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revenue_method": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "guidance_revised": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "eps_min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "eps_max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "eps_mid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "fiscal_period", "guidance_date", "revenue_min", "revenue_max", "revenue_mid", "revenue_prev_min", "revenue_prev_max", "revenue_method", "guidance_revised", "eps_min", "eps_max", "eps_mid" ], "additionalProperties": false }, { "type": "null" } ] }, "prices": { "anyOf": [ { "type": "object", "properties": { "t_minus_1": { "anyOf": [ { "type": "object", "properties": { "date": { "type": "string" }, "close": { "type": "number" } }, "required": [ "date", "close" ], "additionalProperties": false }, { "type": "null" } ] }, "t0": { "anyOf": [ { "type": "object", "properties": { "date": { "type": "string" }, "close": { "type": "number" } }, "required": [ "date", "close" ], "additionalProperties": false }, { "type": "null" } ] }, "t_plus_1": { "anyOf": [ { "type": "object", "properties": { "date": { "type": "string" }, "close": { "type": "number" } }, "required": [ "date", "close" ], "additionalProperties": false }, { "type": "null" } ] }, "t_plus_5": { "anyOf": [ { "type": "object", "properties": { "date": { "type": "string" }, "close": { "type": "number" } }, "required": [ "date", "close" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "t_minus_1", "t0", "t_plus_1", "t_plus_5" ], "additionalProperties": false }, { "type": "null" } ] }, "ratios": { "anyOf": [ { "type": "object", "properties": { "gross_margin_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "operating_margin_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "net_margin_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "return_on_equity_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "revenue_growth_yoy_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pe_ratio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "gross_margin_pct", "operating_margin_pct", "net_margin_pct", "return_on_equity_pct", "revenue_growth_yoy_pct", "pe_ratio" ], "additionalProperties": false }, { "type": "null" } ] }, "options": { "anyOf": [ { "type": "object", "properties": { "put_call_volume_ratio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "interpretation": { "anyOf": [ { "type": "string", "enum": [ "bullish", "neutral", "bearish" ] }, { "type": "null" } ] }, "total_call_volume": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_put_volume": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "avg_spread_percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "liquidity_grade": { "anyOf": [ { "type": "string", "enum": [ "A", "B", "C", "D" ] }, { "type": "null" } ] }, "contracts_with_volume": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expirations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "data_quality": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "no_data", "thin_sample" ] }, "contracts_analyzed": { "type": "number" }, "contracts_with_volume": { "type": "number" }, "total_volume": { "type": "number" } }, "required": [ "status", "contracts_analyzed", "contracts_with_volume", "total_volume" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "put_call_volume_ratio", "interpretation", "total_call_volume", "total_put_volume", "avg_spread_percent", "liquidity_grade", "contracts_with_volume", "expirations", "data_quality" ], "additionalProperties": false }, { "type": "null" } ] }, "short": { "anyOf": [ { "type": "object", "properties": { "shares_short": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "short_float_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "days_to_cover": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "interest_as_of_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "avg_short_volume_ratio_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max_short_volume_ratio_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "days_above_40_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "shares_short", "short_float_pct", "days_to_cover", "interest_as_of_date", "avg_short_volume_ratio_pct", "max_short_volume_ratio_pct", "days_above_40_pct" ], "additionalProperties": false }, { "type": "null" } ] }, "technical_indicators": { "anyOf": [ { "type": "object", "properties": { "rsi_14": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "macd_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "macd_signal": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "macd_histogram": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sma_20": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sma_50": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "rsi_14", "macd_value", "macd_signal", "macd_histogram", "sma_20", "sma_50" ], "additionalProperties": false }, { "type": "null" } ] }, "financial_statements": { "anyOf": [ { "type": "object", "properties": { "as_of_period_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lite": { "type": "object", "properties": { "revenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "gross_profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "operating_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "net_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "eps": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "eps_diluted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cash_from_operations": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "free_cash_flow": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_debt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cash_and_equivalents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_equity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "revenue", "gross_profit", "operating_income", "net_income", "eps", "eps_diluted", "cash_from_operations", "free_cash_flow", "total_debt", "cash_and_equivalents", "total_equity" ], "additionalProperties": false }, "verbose": { "type": "object", "properties": { "income_statement": { "anyOf": [ { "type": "object", "properties": { "ticker": { "type": "string" }, "fiscal_year": { "type": "number" }, "fiscal_quarter": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "period_end": { "type": "string" }, "filing_date": { "type": "string" }, "timeframe": { "type": "string" }, "total_revenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cost_of_revenue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "gross_profit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "operating_expenses": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "operating_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "research_and_development": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "selling_general_admin": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "interest_expense": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "interest_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "other_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "income_before_tax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "income_tax": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "net_income": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "earnings_per_share": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "earnings_per_share_diluted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shares_outstanding": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shares_outstanding_diluted": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "ticker", "fiscal_year", "fiscal_quarter", "period_end", "filing_date", "timeframe", "total_revenue", "cost_of_revenue", "gross_profit", "operating_expenses", "operating_income", "research_and_development", "selling_general_admin", "interest_expense", "interest_income", "other_income", "income_before_tax", "income_tax", "net_income", "earnings_per_share", "earnings_per_share_diluted", "shares_outstanding", "shares_outstanding_diluted" ], "additionalProperties": false }, { "type": "null" } ] }, "balance_sheet": { "anyOf": [ { "type": "object", "properties": { "ticker": { "type": "string" }, "fiscal_year": { "type": "number" }, "fiscal_quarter": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "period_end": { "type": "string" }, "filing_date": { "type": "string" }, "timeframe": { "type": "string" }, "total_assets": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_current_assets": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cash_and_equivalents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "short_term_investments": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "accounts_receivable": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "inventory": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_non_current_assets": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "property_plant_equipment": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "goodwill": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "intangible_assets": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_liabilities": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_current_liabilities": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "accounts_payable": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "short_term_debt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_non_current_liabilities": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "long_term_debt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_equity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "retained_earnings": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "common_stock": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "ticker", "fiscal_year", "fiscal_quarter", "period_end", "filing_date", "timeframe", "total_assets", "total_current_assets", "cash_and_equivalents", "short_term_investments", "accounts_receivable", "inventory", "total_non_current_assets", "property_plant_equipment", "goodwill", "intangible_assets", "total_liabilities", "total_current_liabilities", "accounts_payable", "short_term_debt", "total_non_current_liabilities", "long_term_debt", "total_equity", "retained_earnings", "common_stock" ], "additionalProperties": false }, { "type": "null" } ] }, "cash_flow": { "anyOf": [ { "type": "object", "properties": { "ticker": { "type": "string" }, "fiscal_year": { "type": "number" }, "fiscal_quarter": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "period_end": { "type": "string" }, "filing_date": { "type": "string" }, "timeframe": { "type": "string" }, "net_cash_from_operating": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "depreciation_amortization": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "stock_based_compensation": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "change_in_working_capital": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "net_cash_from_investing": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "capital_expenditures": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "acquisitions": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "investment_purchases": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "investment_sales": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "net_cash_from_financing": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "dividends_paid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "share_repurchases": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "debt_issuance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "debt_repayment": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "net_change_in_cash": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "free_cash_flow": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "ticker", "fiscal_year", "fiscal_quarter", "period_end", "filing_date", "timeframe", "net_cash_from_operating", "depreciation_amortization", "stock_based_compensation", "change_in_working_capital", "net_cash_from_investing", "capital_expenditures", "acquisitions", "investment_purchases", "investment_sales", "net_cash_from_financing", "dividends_paid", "share_repurchases", "debt_issuance", "debt_repayment", "net_change_in_cash", "free_cash_flow" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "income_statement", "balance_sheet", "cash_flow" ], "additionalProperties": false } }, "required": [ "as_of_period_end" ], "additionalProperties": false }, { "type": "null" } ] }, "pre_earnings_context": { "anyOf": [ { "type": "object", "properties": { "run_10d_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "run_30d_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "run_90d_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "percentile_52w": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vix_proxy_close": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vix_percentile": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sp500_vs_200dma_pct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "stock_bars_count": { "type": "number" }, "vix_bars_count": { "type": "number" }, "spy_bars_count": { "type": "number" } }, "required": [ "run_10d_pct", "run_30d_pct", "run_90d_pct", "percentile_52w", "vix_proxy_close", "vix_percentile", "sp500_vs_200dma_pct", "stock_bars_count", "vix_bars_count", "spy_bars_count" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "ticker", "earnings_date", "earnings", "guidance", "prices", "ratios", "options", "short", "technical_indicators", "financial_statements", "pre_earnings_context" ], "additionalProperties": false }, "TickerSentiment": { "type": "object", "properties": { "ticker": { "type": "string" }, "as_of_date": { "type": "string" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "band": { "anyOf": [ { "type": "string", "enum": [ "extreme fear", "fear", "neutral", "greed", "extreme greed" ] }, { "type": "null" } ] }, "coverage": { "type": "string" }, "sub_scores": { "type": "object", "properties": { "trend": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "flow": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "positioning": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "trend", "flow", "positioning" ], "additionalProperties": false }, "components": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "group": { "type": "string", "enum": [ "trend", "flow", "positioning" ] }, "raw": { "type": "number" }, "unit": { "type": "string", "enum": [ "pct", "ratio", "share_pct", "rank", "days" ] }, "percentile": { "type": "number" }, "score": { "type": "number" }, "window": { "type": "string" }, "note": { "type": "string" } }, "required": [ "id", "group", "raw", "unit", "percentile", "score", "window" ], "additionalProperties": false } }, "omitted": { "type": "array", "items": { "type": "object", "properties": { "component": { "type": "string" }, "reason": { "type": "string", "enum": [ "history_accumulating", "thin_chain", "insufficient_history", "no_data" ] } }, "required": [ "component", "reason" ], "additionalProperties": false } }, "delta": { "type": "object", "properties": { "d1": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "d5": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "d20": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "d1", "d5", "d20" ], "additionalProperties": false }, "history": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "score": { "type": "number" }, "coverage": { "type": "string" } }, "required": [ "date", "score", "coverage" ], "additionalProperties": false } }, "flags": { "type": "array", "items": { "type": "string" } }, "context": { "type": "object", "properties": { "next_earnings": { "anyOf": [ { "type": "object", "properties": { "date": { "type": "string" }, "days": { "type": "number" }, "confirmed": { "type": "boolean" } }, "required": [ "date", "days", "confirmed" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "next_earnings" ], "additionalProperties": false }, "derived": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "object", "properties": { "selection": { "type": "string", "enum": [ "full_chain", "partial_chain" ] }, "contracts_analyzed": { "type": "number" }, "expirations_covered": { "type": "number" }, "pages_fetched": { "type": "number" } }, "required": [ "selection", "contracts_analyzed", "expirations_covered", "pages_fetched" ], "additionalProperties": false }, "data_quality": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded", "no_data" ] }, "history": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "accumulating" ] }, "days_collected": { "type": "number" } }, "required": [ "status", "days_collected" ], "additionalProperties": false }, "note": { "type": "string" } }, "required": [ "status", "history" ], "additionalProperties": false }, "methodology": { "type": "object", "properties": { "version": { "type": "string" }, "component_scoring": { "type": "string" }, "composite": { "type": "string" }, "band_cutoffs": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "orientation": { "type": "string" }, "flow_sharing": { "type": "string" } }, "required": [ "version", "component_scoring", "composite", "band_cutoffs", "orientation", "flow_sharing" ], "additionalProperties": false } }, "required": [ "ticker", "as_of_date", "price", "score", "band", "coverage", "sub_scores", "components", "omitted", "delta", "history", "flags", "context", "derived", "scope", "data_quality", "methodology" ], "additionalProperties": false } } } }