API conventions - SEC API for AI

Start by sending an API key in x-api-key. Use the endpoint reference for the request shape and response fields of the route you call.

curl -sS \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/filings/latest?ticker=AAPL&form=10-K"

Authenticate and version requests

Machine requests use x-api-key; do not put an API key in Authorization: Bearer. Browser-only account actions require a signed-in browser session. A human bearer credential is required only where the endpoint reference says so. Use secapi-version to request a dated API version. When it is omitted, SEC API resolves the current published version and returns it in SECAPI-Version. A pinned version can receive additive fields, so parse the fields your application uses and tolerate additional fields.

Keep the evidence that identifies a result

For a material response, store the returned Request-Id, traceparent when present, endpoint, parameters, and retrieval time. For filing-backed results, also retain the accession number, filing URL, period, units, and any route-specific provenance, freshness, warning, or capability fields. You may send x-request-id to correlate a request with your own logs. Keep the returned Request-Id too: it identifies the API request if you need to diagnose it.

Request only the response view you use

Some endpoints support view=default, view=compact, or view=agent.

default is the full documented response.
compact is a smaller endpoint-specific projection.
agent is an endpoint-specific projection for retrieval and citation-oriented workflows.

Views and projected fields vary by route. Confirm support in that route’s reference before depending on a field, and do not assume a compact or agent view includes the metadata in the default view.

Continue list results correctly

When a response returns hasMore and nextCursor, use nextCursor as the next request’s cursor; stop when hasMore is false. Some list endpoints do not paginate. Their reference defines their limit and pagination contract.

Handle failures by status and code

Error responses provide a machine-readable code, message, and request ID. Read them before retrying.

Status	First action
`400`	Correct the request using the endpoint reference.
`401`	Confirm a valid `x-api-key` reached the API.
`402`	Resolve the billing, entitlement, or budget condition in the response.
`403`	Check that the credential and plan are authorized for the resource.
`429`	Honor `Retry-After` when present; use bounded backoff without concurrent retry fan-out.
`5xx`	Retry once with bounded backoff, then retain the request ID for support.

Do not retry a billing, budget, quota, or authorization stop until its stated condition changes. See Troubleshooting for code-specific next actions.

Interpret financial periods before comparing values

Check periodBasis where an endpoint provides it. Balance-sheet values are point-in-time; quarterly income-statement and cash-flow values can be year-to-date as filed. Also compare units, reporting periods, and source context before treating values as comparable. Use REST or an SDK when you need direct control of the request and response. Use hosted MCP when an MCP-aware client needs SEC API tools. Begin with your first request.

​Authenticate and version requests

​Keep the evidence that identifies a result

​Request only the response view you use

​Continue list results correctly

​Handle failures by status and code

​Interpret financial periods before comparing values