{ "openapi": "3.1.0", "info": { "title": "Studying Stocks API", "version": "1.0.0", "summary": "Standardized company financials from SEC EDGAR filings, and our free cash flow valuation.", "description": "Standardized fundamentals for listed US companies, built from SEC EDGAR filings (public domain), and our own discounted cash flow valuation.\n\n- **Beta:** v1 may change while it is in beta; changes are announced in the changelog.\n- **Authentication:** send your key in the `X-Api-Key` header. Keys are created on your profile page by Premium subscribers.\n- **Limits:** 60 requests per minute and 10,000 per day per key.\n- **Not investment advice:** the data is provided as is.\n", "contact": { "name": "Studying Stocks", "url": "https://studyingstocks.com/developers" } }, "servers": [ { "url": "https://studyingstocks.com/api/v1", "description": "This server" } ], "tags": [ { "name": "Companies", "description": "Covered companies, profiles and fundamentals." }, { "name": "Valuation", "description": "Our discounted cash flow model." }, { "name": "Status", "description": "API and data freshness." } ], "security": [ { "ApiKey": [] } ], "paths": { "/companies": { "get": { "operationId": "listCompanies", "tags": [ "Companies" ], "summary": "List companies", "description": "Companies covered by the API: listed companies with SEC EDGAR data. Search by ticker prefix or company name, filter by exchange, page through the results.", "x-docs": { "slug": "companies", "title": "Companies" }, "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Ticker prefix or part of the company name.", "schema": { "type": "string" }, "example": "cisco" }, { "name": "exchange", "in": "query", "required": false, "description": "Exchange, for example `NASDAQ` or `NYSE`.", "schema": { "type": "string" }, "example": "NASDAQ" }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "description": "Companies per page. Default 50, maximum 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "A page of companies.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time (seconds) when the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyList" }, "example": { "data": [ { "symbol": "CSCO", "name": "Cisco Systems, Inc.", "exchange": "Nasdaq", "cik": "0000858877", "sic": "3576", "sic_description": "Industrial and Commercial Machinery and Computer Equipment", "currency": "USD", "first_period_end": "2017-07-29", "last_period_end": "2026-07-25", "data_updated_at": "2026-10-15T02:00:00Z" } ], "meta": { "page": 1, "per_page": 50, "total": 1, "last_page": 1, "source": "SEC EDGAR", "api_version": "v1", "generated_at": "2026-10-16T02:00:00Z" } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthenticated", "message": "Invalid API key.", "docs": "https://studyingstocks.com/developers/errors#unauthenticated" } } } } }, "403": { "description": "The Premium subscription behind the key is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "subscription_inactive", "message": "The Premium subscription for this API key is not active. Renew it to use the API again.", "docs": "https://studyingstocks.com/developers/errors#subscription_inactive" } } } } }, "422": { "description": "A query parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "The per page must not be greater than 100.", "docs": "https://studyingstocks.com/developers/errors#invalid_parameter" } } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit reached. Retry after the number of seconds in the Retry-After header.", "docs": "https://studyingstocks.com/developers/errors#rate_limited" } } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "server_error", "message": "Something went wrong on our side. Try again later.", "docs": "https://studyingstocks.com/developers/errors#server_error" } } } } } }, "x-sample-query": { "search": "cisco" } } }, "/companies/{symbol}": { "get": { "operationId": "getCompany", "tags": [ "Companies" ], "summary": "Company profile", "description": "One company's profile and coverage: identifiers, fiscal year end, the first and last period we have, which line items are available, and a link to its SEC filings.", "x-docs": { "slug": "company-profile", "title": "Company profile" }, "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Ticker symbol of a listed company, for example `CSCO`. Case-insensitive.", "schema": { "type": "string" }, "example": "CSCO" } ], "responses": { "200": { "description": "The company profile.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time (seconds) when the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyProfile" }, "example": { "data": { "symbol": "CSCO", "name": "Cisco Systems, Inc.", "exchange": "Nasdaq", "cik": "0000858877", "sic": "3576", "sic_description": "Industrial and Commercial Machinery and Computer Equipment", "currency": "USD", "first_period_end": "2017-07-29", "last_period_end": "2026-07-25", "data_updated_at": "2026-10-15T02:00:00Z", "fiscal_year_end_month": 7, "coverage": { "first_period": { "period": "2017Q4", "period_end": "2017-07-29" }, "last_period": { "period": "2026Q4", "period_end": "2026-07-25" }, "ttm_periods": 37, "annual_periods": 9, "line_items": [ "revenue", "net_income", "eps_basic", "dividends_per_share", "free_cash_flow", "shares_basic", "shares_diluted", "total_debt", "cash_and_equivalents", "roic", "debt_to_fcf" ] }, "links": { "sec_filings": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000858877&type=10-&dateb=&owner=include&count=40", "financials": "https://studyingstocks.com/api/v1/companies/CSCO/financials", "valuation": "https://studyingstocks.com/api/v1/companies/CSCO/valuation" } }, "meta": { "symbol": "CSCO", "source": "SEC EDGAR", "api_version": "v1", "generated_at": "2026-10-16T02:00:00Z" } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthenticated", "message": "Invalid API key.", "docs": "https://studyingstocks.com/developers/errors#unauthenticated" } } } } }, "403": { "description": "The Premium subscription behind the key is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "subscription_inactive", "message": "The Premium subscription for this API key is not active. Renew it to use the API again.", "docs": "https://studyingstocks.com/developers/errors#subscription_inactive" } } } } }, "404": { "description": "The company is not covered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No listed company with the symbol ZZZZ is covered. See GET /api/v1/companies for the covered companies.", "docs": "https://studyingstocks.com/developers/errors#not_found" } } } } }, "422": { "description": "An unknown query parameter was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "Unknown query parameter: apikey. This endpoint takes no query parameters. Send your API key in the X-Api-Key header, never in the URL.", "docs": "https://studyingstocks.com/developers/errors#invalid_parameter" } } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit reached. Retry after the number of seconds in the Retry-After header.", "docs": "https://studyingstocks.com/developers/errors#rate_limited" } } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "server_error", "message": "Something went wrong on our side. Try again later.", "docs": "https://studyingstocks.com/developers/errors#server_error" } } } } } } } }, "/companies/{symbol}/financials": { "get": { "operationId": "getFinancials", "tags": [ "Companies" ], "summary": "Financials", "description": "Standardized line items per period, newest first. Every value is the trailing twelve months (TTM) ending at the period end; balance sheet items (`total_debt`, `cash_and_equivalents`) are the value at the period end. `period=annual` keeps only the fiscal year ends.\n\nA period is left out when none of the requested items has a value for it, and an item without a value is omitted from `values`.", "x-docs": { "slug": "financials", "title": "Financials" }, "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Ticker symbol of a listed company, for example `CSCO`. Case-insensitive.", "schema": { "type": "string" }, "example": "CSCO" }, { "name": "period", "in": "query", "required": false, "description": "`ttm` (default): the trailing twelve months at each quarter end. `annual`: the fiscal year ends only. Discrete quarters are not available yet.", "schema": { "type": "string", "enum": [ "ttm", "annual" ], "default": "ttm" } }, { "name": "items", "in": "query", "required": false, "description": "Comma-separated line items to return. Default: all. One of: `revenue`, `net_income`, `eps_basic`, `dividends_per_share`, `free_cash_flow`, `shares_basic`, `shares_diluted`, `total_debt`, `cash_and_equivalents`, `roic`, `debt_to_fcf`.", "schema": { "type": "string" }, "example": "revenue,free_cash_flow" }, { "name": "from", "in": "query", "required": false, "description": "Only periods with a period end on or after this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Only periods with a period end on or before this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of periods. Default 20, maximum 40.", "schema": { "type": "integer", "minimum": 1, "maximum": 40, "default": 20 } } ], "responses": { "200": { "description": "Periods with their values.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time (seconds) when the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Financials" }, "example": { "data": [ { "period": "2026Q4", "period_end": "2026-07-25", "fiscal_year": 2026, "fiscal_quarter": 4, "values": { "revenue": 63325000000, "free_cash_flow": 12767000000 } } ], "meta": { "symbol": "CSCO", "currency": "USD", "period": "ttm", "items": [ "revenue", "free_cash_flow" ], "count": 1, "filings_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000858877&type=10-&dateb=&owner=include&count=40", "source": "SEC EDGAR", "api_version": "v1", "generated_at": "2026-10-16T02:00:00Z" } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthenticated", "message": "Invalid API key.", "docs": "https://studyingstocks.com/developers/errors#unauthenticated" } } } } }, "403": { "description": "The Premium subscription behind the key is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "subscription_inactive", "message": "The Premium subscription for this API key is not active. Renew it to use the API again.", "docs": "https://studyingstocks.com/developers/errors#subscription_inactive" } } } } }, "404": { "description": "The company is not covered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No SEC EDGAR data is available for ZZZZ yet.", "docs": "https://studyingstocks.com/developers/errors#not_found" } } } } }, "422": { "description": "A query parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "Unknown item: sales. Valid items: revenue, net_income, eps_basic, dividends_per_share, free_cash_flow, shares_basic, shares_diluted, total_debt, cash_and_equivalents, roic, debt_to_fcf.", "docs": "https://studyingstocks.com/developers/errors#invalid_parameter" } } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit reached. Retry after the number of seconds in the Retry-After header.", "docs": "https://studyingstocks.com/developers/errors#rate_limited" } } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "server_error", "message": "Something went wrong on our side. Try again later.", "docs": "https://studyingstocks.com/developers/errors#server_error" } } } } } }, "x-sample-query": { "period": "annual", "items": "revenue,free_cash_flow", "limit": "5" } } }, "/companies/{symbol}/financials/revisions": { "get": { "operationId": "getRevisions", "tags": [ "Companies" ], "summary": "Revisions", "description": "Restatement history: every period and line item whose value changed after we first recorded it, with each earlier value and when we recorded it. `recorded_at` is when our sync saw the value, not the filing date. The filing that restated a value can be found through the company's SEC filings link.", "x-docs": { "slug": "revisions", "title": "Revisions" }, "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Ticker symbol of a listed company, for example `CSCO`. Case-insensitive.", "schema": { "type": "string" }, "example": "CSCO" }, { "name": "items", "in": "query", "required": false, "description": "Comma-separated line items to check. Default: all. One of: `revenue`, `net_income`, `eps_basic`, `dividends_per_share`, `free_cash_flow`, `shares_basic`, `shares_diluted`, `total_debt`, `cash_and_equivalents`, `roic`, `debt_to_fcf`.", "schema": { "type": "string" }, "example": "revenue,free_cash_flow" }, { "name": "from", "in": "query", "required": false, "description": "Only revisions with a period end on or after this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Only revisions with a period end on or before this date (`YYYY-MM-DD`).", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of revised period and item pairs. Default 50, maximum 200.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Revised values, newest period first. Empty when nothing was revised.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time (seconds) when the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revisions" }, "example": { "data": [ { "period": "2026Q3", "period_end": "2026-04-25", "item": "revenue", "current_value": 61500000000, "versions": [ { "version": 1, "value": 61200000000, "current": false, "recorded_at": "2026-05-20T02:00:00Z" }, { "version": 2, "value": 61500000000, "current": true, "recorded_at": "2026-08-14T02:00:00Z" } ] } ], "meta": { "symbol": "CSCO", "currency": "USD", "items": [ "revenue" ], "count": 1, "source": "SEC EDGAR", "api_version": "v1", "generated_at": "2026-10-16T02:00:00Z" } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthenticated", "message": "Invalid API key.", "docs": "https://studyingstocks.com/developers/errors#unauthenticated" } } } } }, "403": { "description": "The Premium subscription behind the key is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "subscription_inactive", "message": "The Premium subscription for this API key is not active. Renew it to use the API again.", "docs": "https://studyingstocks.com/developers/errors#subscription_inactive" } } } } }, "404": { "description": "The company is not covered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No SEC EDGAR data is available for ZZZZ yet.", "docs": "https://studyingstocks.com/developers/errors#not_found" } } } } }, "422": { "description": "A query parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "The from does not match the format Y-m-d.", "docs": "https://studyingstocks.com/developers/errors#invalid_parameter" } } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit reached. Retry after the number of seconds in the Retry-After header.", "docs": "https://studyingstocks.com/developers/errors#rate_limited" } } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "server_error", "message": "Something went wrong on our side. Try again later.", "docs": "https://studyingstocks.com/developers/errors#server_error" } } } } } }, "x-sample-query": { "items": "revenue" } } }, "/companies/{symbol}/valuation": { "get": { "operationId": "getValuation", "tags": [ "Valuation" ], "summary": "Valuation", "description": "Our discounted cash flow (DCF) valuation, built only from the company's SEC filings: a 10-year free cash flow projection, the assumptions, and the fair value per share. When a free cash flow model does not fit the company (banks, insurers and real estate companies, or too little history) the response has `meaningful: false` and a `reason`. See the valuation methodology guide.", "x-docs": { "slug": "valuation", "title": "Valuation" }, "parameters": [ { "name": "symbol", "in": "path", "required": true, "description": "Ticker symbol of a listed company, for example `CSCO`. Case-insensitive.", "schema": { "type": "string" }, "example": "CSCO" } ], "responses": { "200": { "description": "The valuation, or the reason there is none.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time (seconds) when the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Valuation" }, "example": { "data": { "meaningful": true, "fair_value_per_share": 61.42, "fair_equity_value": 245000000000, "enterprise_value": 249000000000, "net_debt": 4000000000, "currency": "USD", "assumptions": { "required_return": 0.085, "perpetual_growth": 0.025, "projection_years": 10, "stage_one_years": 5, "stage_one_growth": 0.04 }, "inputs": { "as_of": "2026-07-25", "balance_sheet_as_of": "2026-07-25", "total_debt": 28000000000, "cash_and_equivalents": 24000000000, "shares": 4000000000 }, "free_cash_flow_history": [ { "fiscal_year": 2025, "free_cash_flow": 11500000000 }, { "fiscal_year": 2026, "free_cash_flow": 12767000000 } ], "free_cash_flow_projection": [ { "fiscal_year": 2027, "free_cash_flow": 13300000000, "growth_rate": 0.04, "discount_factor": 1.085, "present_value": 12258064516.13 } ], "terminal_value": { "value": 330000000000, "present_value": 145000000000 }, "reason": null, "methodology_version": "1" }, "meta": { "symbol": "CSCO", "currency": "USD", "source": "SEC EDGAR", "api_version": "v1", "generated_at": "2026-10-16T02:00:00Z" } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthenticated", "message": "Invalid API key.", "docs": "https://studyingstocks.com/developers/errors#unauthenticated" } } } } }, "403": { "description": "The Premium subscription behind the key is not active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "subscription_inactive", "message": "The Premium subscription for this API key is not active. Renew it to use the API again.", "docs": "https://studyingstocks.com/developers/errors#subscription_inactive" } } } } }, "404": { "description": "The company is not covered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No SEC EDGAR data is available for ZZZZ yet.", "docs": "https://studyingstocks.com/developers/errors#not_found" } } } } }, "422": { "description": "An unknown query parameter was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "Unknown query parameter: apikey. This endpoint takes no query parameters. Send your API key in the X-Api-Key header, never in the URL.", "docs": "https://studyingstocks.com/developers/errors#invalid_parameter" } } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit reached. Retry after the number of seconds in the Retry-After header.", "docs": "https://studyingstocks.com/developers/errors#rate_limited" } } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "server_error", "message": "Something went wrong on our side. Try again later.", "docs": "https://studyingstocks.com/developers/errors#server_error" } } } } } } } }, "/status": { "get": { "operationId": "getStatus", "tags": [ "Status" ], "summary": "Status", "description": "API version, data freshness and the number of covered companies. Needs no API key; limited to 60 requests per minute per IP address.", "security": [], "x-docs": { "slug": "status", "title": "Status" }, "responses": { "200": { "description": "The API is up.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix time (seconds) when the window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" }, "example": { "data": { "status": "ok", "api_version": "v1", "companies_covered": 4210, "data_updated_at": "2026-10-16T02:00:00Z" }, "meta": { "source": "SEC EDGAR", "api_version": "v1", "generated_at": "2026-10-16T02:00:00Z" } } } } }, "422": { "description": "An unknown query parameter was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "Unknown query parameter: apikey. This endpoint takes no query parameters. Send your API key in the X-Api-Key header, never in the URL.", "docs": "https://studyingstocks.com/developers/errors#invalid_parameter" } } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit reached. Retry after the number of seconds in the Retry-After header.", "docs": "https://studyingstocks.com/developers/errors#rate_limited" } } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "server_error", "message": "Something went wrong on our side. Try again later.", "docs": "https://studyingstocks.com/developers/errors#server_error" } } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiDocument", "tags": [ "Status" ], "summary": "OpenAPI document", "description": "This specification as OpenAPI 3.1 JSON. Needs no API key.", "security": [], "x-docs": { "hidden": true }, "responses": { "200": { "description": "The OpenAPI document.", "content": { "application/json": { "schema": { "type": "object", "description": "An OpenAPI 3.1 document.", "required": [ "openapi", "info", "servers", "tags", "security", "paths", "components" ], "properties": { "openapi": { "type": "string" }, "info": { "type": "object", "additionalProperties": { "x-any-json": true, "type": [ "object", "array", "string", "integer", "number", "boolean", "null" ] } }, "servers": { "type": "array", "items": { "x-any-json": true, "type": [ "object", "array", "string", "integer", "number", "boolean", "null" ] } }, "tags": { "type": "array", "items": { "x-any-json": true, "type": [ "object", "array", "string", "integer", "number", "boolean", "null" ] } }, "security": { "type": "array", "items": { "x-any-json": true, "type": [ "object", "array", "string", "integer", "number", "boolean", "null" ] } }, "paths": { "type": "object", "additionalProperties": { "x-any-json": true, "type": [ "object", "array", "string", "integer", "number", "boolean", "null" ] } }, "components": { "type": "object", "additionalProperties": { "x-any-json": true, "type": [ "object", "array", "string", "integer", "number", "boolean", "null" ] } } }, "additionalProperties": false } } } }, "422": { "description": "An unknown query parameter was sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_parameter", "message": "Unknown query parameter: apikey. This endpoint takes no query parameters. Send your API key in the X-Api-Key header, never in the URL.", "docs": "https://studyingstocks.com/developers/errors#invalid_parameter" } } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit reached. Retry after the number of seconds in the Retry-After header.", "docs": "https://studyingstocks.com/developers/errors#rate_limited" } } } } }, "500": { "description": "Something went wrong on our side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "server_error", "message": "Something went wrong on our side. Try again later.", "docs": "https://studyingstocks.com/developers/errors#server_error" } } } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Your API key, `ss_live_` followed by 40 characters. Premium subscribers create it on their profile page. Never put it in a URL." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "docs" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated", "subscription_inactive", "not_found", "method_not_allowed", "invalid_parameter", "rate_limited", "server_error" ] }, "message": { "type": "string" }, "docs": { "type": "string", "format": "uri", "description": "Link to the explanation of this error code." }, "details": { "type": "object", "description": "Messages per parameter name, for invalid_parameter.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "additionalProperties": false } }, "additionalProperties": false }, "Company": { "type": "object", "required": [ "symbol", "name", "exchange", "cik", "sic", "sic_description", "currency", "first_period_end", "last_period_end", "data_updated_at" ], "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "name": { "type": [ "string", "null" ], "description": "Company name." }, "exchange": { "type": [ "string", "null" ], "description": "Listing exchange." }, "cik": { "type": [ "string", "null" ], "description": "SEC Central Index Key, ten digits." }, "sic": { "type": [ "string", "null" ], "description": "SEC Standard Industrial Classification code." }, "sic_description": { "type": [ "string", "null" ], "description": "Name of the SIC major group (the first two digits of the code)." }, "currency": { "type": "string", "description": "Reporting currency of every monetary value." }, "first_period_end": { "type": [ "string", "null" ], "format": "date", "description": "End date of the oldest period we have." }, "last_period_end": { "type": [ "string", "null" ], "format": "date", "description": "End date of the latest period we have." }, "data_updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When we last synchronized this company with SEC EDGAR." } }, "additionalProperties": false }, "CompanyList": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "meta": { "type": "object", "required": [ "page", "per_page", "total", "last_page", "source", "api_version", "generated_at" ], "properties": { "source": { "type": "string", "description": "Where the data comes from: always SEC EDGAR (calculated items are derived from it)." }, "api_version": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time", "description": "When this response was generated (responses are cached for a few hours)." }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false }, "CompanyProfile": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "symbol", "name", "exchange", "cik", "sic", "sic_description", "currency", "first_period_end", "last_period_end", "data_updated_at", "fiscal_year_end_month", "coverage", "links" ], "properties": { "symbol": { "type": "string", "description": "Ticker symbol." }, "name": { "type": [ "string", "null" ], "description": "Company name." }, "exchange": { "type": [ "string", "null" ], "description": "Listing exchange." }, "cik": { "type": [ "string", "null" ], "description": "SEC Central Index Key, ten digits." }, "sic": { "type": [ "string", "null" ], "description": "SEC Standard Industrial Classification code." }, "sic_description": { "type": [ "string", "null" ], "description": "Name of the SIC major group (the first two digits of the code)." }, "currency": { "type": "string", "description": "Reporting currency of every monetary value." }, "first_period_end": { "type": [ "string", "null" ], "format": "date", "description": "End date of the oldest period we have." }, "last_period_end": { "type": [ "string", "null" ], "format": "date", "description": "End date of the latest period we have." }, "data_updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When we last synchronized this company with SEC EDGAR." }, "fiscal_year_end_month": { "type": [ "integer", "null" ], "description": "Month (1-12) the fiscal year ends in." }, "coverage": { "type": "object", "required": [ "first_period", "last_period", "ttm_periods", "annual_periods", "line_items" ], "properties": { "first_period": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "period", "period_end" ], "properties": { "period": { "type": [ "string", "null" ] }, "period_end": { "type": "string", "format": "date" } }, "additionalProperties": false } ] }, "last_period": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "period", "period_end" ], "properties": { "period": { "type": [ "string", "null" ] }, "period_end": { "type": "string", "format": "date" } }, "additionalProperties": false } ] }, "ttm_periods": { "type": "integer", "description": "Number of quarter-end periods." }, "annual_periods": { "type": "integer", "description": "Number of fiscal years." }, "line_items": { "type": "array", "items": { "type": "string", "enum": [ "revenue", "net_income", "eps_basic", "dividends_per_share", "free_cash_flow", "shares_basic", "shares_diluted", "total_debt", "cash_and_equivalents", "roic", "debt_to_fcf" ] }, "description": "Line items with at least one value." } }, "additionalProperties": false }, "links": { "type": "object", "required": [ "sec_filings", "financials", "valuation" ], "properties": { "sec_filings": { "type": [ "string", "null" ], "format": "uri", "description": "SEC's list of the company's periodic filings." }, "financials": { "type": "string", "format": "uri" }, "valuation": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "additionalProperties": false }, "meta": { "type": "object", "required": [ "symbol", "source", "api_version", "generated_at" ], "properties": { "source": { "type": "string", "description": "Where the data comes from: always SEC EDGAR (calculated items are derived from it)." }, "api_version": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time", "description": "When this response was generated (responses are cached for a few hours)." }, "symbol": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "Financials": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "period", "period_end", "fiscal_year", "fiscal_quarter", "values" ], "properties": { "period": { "type": "string", "description": "Fiscal period label: `2026Q4` for TTM periods, `FY2026` for annual ones." }, "period_end": { "type": "string", "format": "date" }, "fiscal_year": { "type": "integer" }, "fiscal_quarter": { "type": "integer", "minimum": 1, "maximum": 4 }, "values": { "type": "object", "description": "Line items by name; items without a value are omitted.", "properties": { "revenue": { "type": "number", "description": "Revenue." }, "net_income": { "type": "number", "description": "Net income attributable to common shareholders." }, "eps_basic": { "type": "number", "description": "Earnings per share, basic. Per-share values are decimals." }, "dividends_per_share": { "type": "number", "description": "Dividends declared per share." }, "free_cash_flow": { "type": "number", "description": "Calculated: operating cash flow minus capital expenditure." }, "shares_basic": { "type": "number", "description": "Weighted average basic shares outstanding." }, "shares_diluted": { "type": "number", "description": "Weighted average diluted shares outstanding." }, "total_debt": { "type": "number", "description": "Total debt at the period end (long-term debt, current maturities and short-term borrowings)." }, "cash_and_equivalents": { "type": "number", "description": "Cash, cash equivalents and short-term investments at the period end." }, "roic": { "type": "number", "description": "Calculated: return on invested capital as a fraction (0.18 = 18%)." }, "debt_to_fcf": { "type": "number", "description": "Calculated: total debt divided by free cash flow, in years. Omitted when free cash flow is not positive." } }, "additionalProperties": false } }, "additionalProperties": false } }, "meta": { "type": "object", "required": [ "symbol", "currency", "period", "items", "count", "source", "api_version", "generated_at" ], "properties": { "source": { "type": "string", "description": "Where the data comes from: always SEC EDGAR (calculated items are derived from it)." }, "api_version": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time", "description": "When this response was generated (responses are cached for a few hours)." }, "symbol": { "type": "string" }, "currency": { "type": "string" }, "period": { "type": "string", "enum": [ "ttm", "annual" ] }, "items": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer" }, "filings_url": { "type": [ "string", "null" ], "format": "uri", "description": "SEC's list of the company's periodic filings, where each value can be checked." } }, "additionalProperties": false } }, "additionalProperties": false }, "Revisions": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "period", "period_end", "item", "current_value", "versions" ], "properties": { "period": { "type": "string" }, "period_end": { "type": "string", "format": "date" }, "item": { "type": "string", "enum": [ "revenue", "net_income", "eps_basic", "dividends_per_share", "free_cash_flow", "shares_basic", "shares_diluted", "total_debt", "cash_and_equivalents", "roic", "debt_to_fcf" ] }, "current_value": { "type": [ "number", "null" ] }, "versions": { "type": "array", "items": { "type": "object", "required": [ "version", "value", "current", "recorded_at" ], "properties": { "version": { "type": "integer" }, "value": { "type": "number" }, "current": { "type": "boolean" }, "recorded_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When our sync recorded this value." } }, "additionalProperties": false } } }, "additionalProperties": false } }, "meta": { "type": "object", "required": [ "symbol", "currency", "items", "count", "source", "api_version", "generated_at" ], "properties": { "source": { "type": "string", "description": "Where the data comes from: always SEC EDGAR (calculated items are derived from it)." }, "api_version": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time", "description": "When this response was generated (responses are cached for a few hours)." }, "symbol": { "type": "string" }, "currency": { "type": "string" }, "items": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false }, "Valuation": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "meaningful", "reason", "methodology_version" ], "properties": { "meaningful": { "type": "boolean", "description": "`false` when a free cash flow model does not fit this company; see `reason`." }, "reason": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "no_industry_code", "financial_company", "insufficient_history", "no_share_count", "missing_balance_sheet", "not_calculable" ] }, "message": { "type": "string" } }, "additionalProperties": false } ] }, "methodology_version": { "type": "string" }, "fair_value_per_share": { "type": "number", "description": "Fair value per share, in the reporting currency." }, "fair_equity_value": { "type": "number" }, "enterprise_value": { "type": "number", "description": "Present value of the projected free cash flows and the terminal value." }, "net_debt": { "type": "number" }, "currency": { "type": "string" }, "assumptions": { "type": "object", "required": [ "required_return", "perpetual_growth", "projection_years", "stage_one_years", "stage_one_growth" ], "properties": { "required_return": { "type": "number", "description": "Discount rate as a fraction." }, "perpetual_growth": { "type": "number", "description": "Growth after the projection, as a fraction." }, "projection_years": { "type": "integer" }, "stage_one_years": { "type": "integer" }, "stage_one_growth": { "type": "number", "description": "Yearly growth in the first stage, as a fraction." } }, "additionalProperties": false }, "inputs": { "type": "object", "required": [ "as_of", "balance_sheet_as_of", "total_debt", "cash_and_equivalents", "shares" ], "properties": { "as_of": { "type": "string", "format": "date", "description": "Period end of the latest period, where the share count is taken from." }, "balance_sheet_as_of": { "type": "string", "format": "date", "description": "Oldest period end that debt and cash are taken from: the newest period that reports each." }, "total_debt": { "type": "number" }, "cash_and_equivalents": { "type": "number" }, "shares": { "type": "number" } }, "additionalProperties": false }, "free_cash_flow_history": { "type": "array", "items": { "type": "object", "required": [ "fiscal_year", "free_cash_flow" ], "properties": { "fiscal_year": { "type": "integer" }, "free_cash_flow": { "type": "number" } }, "additionalProperties": false } }, "free_cash_flow_projection": { "type": "array", "items": { "type": "object", "required": [ "fiscal_year", "free_cash_flow", "growth_rate", "discount_factor", "present_value" ], "properties": { "fiscal_year": { "type": "integer" }, "free_cash_flow": { "type": "number" }, "growth_rate": { "type": "number" }, "discount_factor": { "type": [ "number", "null" ] }, "present_value": { "type": [ "number", "null" ] } }, "additionalProperties": false } }, "terminal_value": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "value", "present_value" ], "properties": { "value": { "type": "number" }, "present_value": { "type": "number" } }, "additionalProperties": false } ] } }, "additionalProperties": false }, "meta": { "type": "object", "required": [ "symbol", "currency", "source", "api_version", "generated_at" ], "properties": { "source": { "type": "string", "description": "Where the data comes from: always SEC EDGAR (calculated items are derived from it)." }, "api_version": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time", "description": "When this response was generated (responses are cached for a few hours)." }, "symbol": { "type": "string" }, "currency": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "Status": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "object", "required": [ "status", "api_version", "companies_covered", "data_updated_at" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "api_version": { "type": "string" }, "companies_covered": { "type": "integer" }, "data_updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the most recent company was synchronized with SEC EDGAR." } }, "additionalProperties": false }, "meta": { "type": "object", "required": [ "api_version", "generated_at" ], "properties": { "source": { "type": "string", "description": "Where the data comes from: always SEC EDGAR (calculated items are derived from it)." }, "api_version": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time", "description": "When this response was generated (responses are cached for a few hours)." } }, "additionalProperties": false } }, "additionalProperties": false } } } }