# API basics

Every route of the SEC Blast API follows these rules.

## Base address and key

Every route is under `https://api.secblast.com/v3`. Send your API key with every request; only a few status routes, such as [`GET /v3/health`](https://www.secblast.com/docs/reference/get-health), need none. [Authentication](https://www.secblast.com/docs/authentication) shows the three ways to send it.

## Lists and paging

Every list answers with the same envelope: `{ data, has_more, next_cursor }`. While `has_more` is true, send the same request again with `cursor` set to `next_cursor`. The same loop then reads every list that takes a cursor; [Pagination](https://www.secblast.com/docs/pagination) has it.

## Errors

A failed request gets an HTTP status and a JSON problem body (RFC 9457, `application/problem+json`) with a stable `code` and a `request_id`. Branch on `code`: it does not change, while the wording of `title` and `detail` may. [Errors](https://www.secblast.com/docs/errors) lists every code.

## Unknown parameters are refused

A query parameter that the route does not define gets `400` with the code `unknown_parameter`, and `parameter` names it. A misspelled filter therefore fails at once instead of returning unfiltered data.

## Several values in one parameter

A parameter that takes several values takes them separated by commas, such as `form=8-K,10-Q`. More values than the parameter takes get `400` `too_many_values`, and `max` says how many it takes.

## Dates and times

Dates are written `YYYY-MM-DD`, such as `2026-11-16`. Times are RFC 3339 in UTC, such as `2026-11-16T21:12:33Z`, so you never have to guess a time zone.

## Numbers in responses

Amounts and quantities from filings are JSON strings, so no precision is lost: `"shares": "2399"`, `"price": "351.36"`. They appear in:

* insider transactions and holdings (`shares`, `price`, `total_value`);
* 13F holdings (`value_usd`, `shares_or_principal`);
* XBRL facts, statements, frames, and series (`value`).

Parse them as decimals, such as `Decimal("351.36")` in Python. Counts, sizes, `confidence`, and `score` are JSON numbers.

## Request IDs

Every response has an `X-Request-Id` header, and every problem body repeats it as `request_id`. Quote it when you contact support, so we can find your request.

## Methods

Routes that read take `GET`, and every path also answers `HEAD` and `OPTIONS`. The webhook routes also take `POST`, `PATCH`, and `DELETE`, as their reference pages show. Any other method gets `405`.

## Calling from a browser

The API allows cross-origin requests, so a web page can call it directly, as the [console](https://www.secblast.com/console) does. Anyone who opens such a page can read the key it sends.

## Live filings and when they become final

A new filing arrives live with `status` `provisional`, and you can read it at once. It becomes `final` when SEC's nightly feed file for its day confirms it; the [stream](https://www.secblast.com/docs/stream) and [webhooks](https://www.secblast.com/docs/webhooks) send that change as `filing.updated`. To list only confirmed filings, pass `status=final`.

## Values from SEC's daily data

Some values come from SEC's daily submissions data, not from the filing itself: acceptance times, report periods, company records, SEC's own filing lists, and tickers. A response that can carry them has a `snapshot` field, `{ available, date }`. `date` is the day of SEC's data the response uses. When `available` is `false`, SEC's data was not used, and the response comes from SEC Blast's own records alone.

