> ## Documentation Index
> Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API conventions

> Make authenticated SEC API requests, interpret response context, and handle failures predictably

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.

```bash theme={null}
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](/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](/mcp-install) when an MCP-aware client needs SEC API tools. Begin with [your first request](/getting-started).