# Agent skill

> API version: v1

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](https://studyingstocks.com/llms.txt). Full docs: [llms-full.txt](https://studyingstocks.com/llms-full.txt). Any page as Markdown: add `.md` to its URL.
- OpenAPI 3.1: `https://studyingstocks.com/api/v1/openapi.json`.