Guides

Agent skill

View as Markdown

Use this file to call the Studying Stocks API correctly.

What the API is

Read-only JSON API with standardized fundamentals of listed US companies from SEC EDGAR filings, and a free cash flow valuation. Base URL: https://studyingstocks.com/api/v1. Values are in the reporting currency (USD), in units (not thousands). All data comes from SEC filings or is calculated from them.

Authenticate

Send X-Api-Key: <key> on every request except GET /status. The user supplies the key (ss_live_ + 40 characters). Never put it in a URL, a log or a message to the user. Limits: 60 requests per minute and 10,000 per day.

Which endpoint for what

The user wants Call
To know whether a company is covered, or to find a ticker GET /companies?search=<name or ticker>
A company's industry, fiscal year end, or how much history we have GET /companies/{symbol}
Revenue, profit, cash flow, debt, shares, ROIC... over time GET /companies/{symbol}/financials?items=...
Whether a past number was restated GET /companies/{symbol}/financials/revisions
A fair value per share, or the free cash flow projection GET /companies/{symbol}/valuation
Whether the API is up and how fresh the data is GET /status

Periods

  • period=ttm (default): trailing twelve months at each quarter end. period=annual: fiscal year ends only. Rows are newest first.
  • Labels follow the company's own fiscal calendar (2026Q4, FY2026). Use period_end to compare companies on dates.
  • limit defaults to 20 and is at most 40. Use from and to (YYYY-MM-DD, on period_end).
  • Items: revenue, net_income, eps_basic, dividends_per_share, free_cash_flow, shares_basic, shares_diluted, total_debt, cash_and_equivalents, roic (a fraction), debt_to_fcf (years). An item without a value is missing from values: do not treat that as zero.
  • Not available yet: period=quarter, eps_diluted, operating_cash_flow, capital_expenditure.

Valuation

Check data.meaningful first. When false, tell the user data.reason.message and do not invent a value. When true, fair_value_per_share comes from a 10-year projection at an 8.5% required return and 2.5% perpetual growth; report the assumptions with the number. It is not investment advice.

Errors

Every error is {"error": {"code", "message", "docs"}}. Branch on code:

  • unauthenticated (401): the key is missing or wrong. Ask the user for a valid key.
  • subscription_inactive (403): the Premium subscription behind the key is not active.
  • not_found (404): not covered, or no SEC data yet. Do not guess another symbol.
  • invalid_parameter (422): fix the parameter named in the message.
  • rate_limited (429): wait Retry-After seconds, then retry.
  • server_error (500): retry later.

More

  • Docs index: llms.txt. Full docs: llms-full.txt. Any page as Markdown: add .md to its URL.
  • OpenAPI 3.1: https://studyingstocks.com/api/v1/openapi.json.
PreviousUsing the API from AI agents NextInteractive reference