# SEC API (secapi.ai) — agent rules

Drop this file into your repo as `AGENTS.md`, `CLAUDE.md`, or `.cursor/rules/secapi.md`
so your coding agent uses SEC API correctly. It works alongside the hosted MCP
server and the REST API.

## What this is

SEC API (secapi.ai) is the system of record for SEC and public-market data:
filings, statements, ownership, governance, factors, and market data — exposed
over REST, typed SDKs, a CLI, and a hosted MCP server, all on one provenance-first
contract model.

- REST API: `https://api.secapi.ai`
- Hosted MCP: `https://api.secapi.ai/mcp`
- Docs: `https://docs.secapi.ai`

## Connect (hosted MCP)

```bash
claude mcp add --transport http secapi https://api.secapi.ai/mcp \
  --header "x-api-key: YOUR_API_KEY"
```

Other clients (Claude Desktop, Cursor, Codex, Windsurf) and the full install matrix:
`https://secapi.ai/agents`.

## Rules

- **Auth:** authenticate with the `x-api-key` header. Never send the API key as
  `Authorization: Bearer` — bearer tokens are browser/session credentials, not API keys.
- **Resolve first:** resolve entities (ticker, CIK, CUSIP, ISIN, FIGI) before
  querying, and pass the resolved 10-digit CIK downstream. Never guess a CIK.
- **Prefer structure:** prefer structured SEC API endpoints and MCP tools over raw
  filing text. Start with compact bundles (`/v1/companies/overview`,
  `/v1/intelligence/company`) before pulling atomic routes.
- **Carry metadata:** carry freshness, provenance, `requestId`, and trace metadata
  through to every answer.
- **Cite filings:** when a number comes from a filing, cite the accession number and
  the filing page. Keep extracted filing facts separate from your interpretation; if
  a claim cannot be tied to a filing or a structured field, label it inference.
- **Respect budgets:** check `GET /v1/billing` and `GET /v1/limits` before expensive
  or repeated workflows, and stop if the server signals a budget cap or an approval
  requirement. Back off on `429`; tolerate `503` from beta-gated surfaces.

## Endpoint quick reference

- Resolve a name: `GET /v1/entities/resolve?name=…` (overview/segments accept only `ticker` or `cik`)
- Entity + overview: `GET /v1/companies/overview?ticker=…&include=segments,footnotes,dilution`
- Business breakdown: `GET /v1/companies/segments?ticker=…&segment_type=product|geographic|operating`
- Financials: `GET /v1/companies/{income-statements|balance-sheets|cash-flow-statements|financials|ratios}?ticker=…`
- Filings + sections: `GET /v1/filings`, `POST /v1/intelligence/query` (10-K Item 1 / 1A / 7)
- Ownership (company holders): `GET /v1/owners/institutional/ticker?ticker=…` + insiders `GET /v1/insiders?ticker=…&forms=3,4,5`
- Ownership (a manager's 13F portfolio): `GET /v1/owners/13f?cik=…` (keyed by the filer's CIK, not the issuer)
- Factors: `GET /v1/factors/exposures?symbols=…`, `GET /v1/factors/decomposition?symbol=…`
- Dilution: `GET /v1/dilution/score?ticker=…`
- Macro: `GET /v1/macro/high-signal-pack?country=…`, `GET /v1/macro/regimes?country=…`
- Guardrails: `GET /v1/billing`, `GET /v1/limits`

Full reference: `https://docs.secapi.ai/api-reference`. Installable skills:
`npx skills add secapi-ai/secapi-skills --global`.