Conventions
These rules hold for every endpoint. The endpoint reference only describes what is specific to one endpoint, so it is worth reading this page once.
Base URL and version
All endpoints live under one versioned base URL. The version changes only for a breaking change; new fields and new endpoints can appear at any time, so ignore fields you do not know rather than rejecting them. The changelog lists every change and what counts as breaking.
https://api.algoum.de/v1Authentication
Send your API key as a bearer token on every request. There is no other way in — no cookies, no key in the query string, so a key cannot leak through a browser history or a server log. A missing or invalid key answers 401.
Authorization: Bearer <your key>Response envelope
Every successful response has the same two top-level fields: data carries the payload — an object for a single record, an array for a list — and meta describes the response.
| meta field | Meaning |
|---|---|
request_id | Identifier of this request. It is also returned in the X-Request-Id header. Quote it in a support request. |
source | Where the data comes from, for example sec_edgar. |
data_freshness | Filing time of the most recently processed filing. Absent while no data has been imported — no freshness is claimed in that case. |
next_cursor | Cursor for the next page, or null at the end of a list. |
warnings | Notes about your request that did not prevent an answer. Empty in the normal case. |
Paging
List endpoints return at most limit records, 50 by default and 500 at most; a larger value is capped rather than rejected. To read on, pass meta.next_cursor back as cursor. The cursor is opaque: treat it as a black box, because its content is not part of the contract and may change. A cursor that cannot be read answers 400.
Each list endpoint has a fixed sort order, stated in its own description. It cannot be chosen through a parameter — that is what keeps a cursor stable while you page through it.
Filtering
Most endpoints accept either ticker or cik to select a company; the ticker is the convenient one, the CIK the unambiguous one. Date windows use from and to in YYYY-MM-DD form and both ends are inclusive.
Unknown parameters are reported, not rejected
A query parameter an endpoint does not know does not cause an error — extra parameters such as cache busters should not break a working client. Instead it is reported in meta.warnings, so a typo like ?tickr=AAPL does not silently return an unfiltered result.
{
"meta": {
"request_id": "req_01K4W7YV8Q2N",
"source": "sec_edgar",
"next_cursor": null,
"warnings": ["Unknown query parameter \"tickr\"."]
},
"data": []
}Times and dates
Timestamps are in Eastern Time with an explicit offset, for example 2026-07-11T21:03:00-04:00 — the time zone the SEC reports its filings in, so the time in filed_at matches the original filing. The offset switches with US daylight saving time between -04:00 and -05:00; convert to UTC yourself if you need it. Pure dates such as transaction_date carry no time and no zone.
How fresh the data is
meta.data_freshness tells you how far the data behind a response reaches. For the picture per source — last filing seen and last successful import — query the status endpoint; it is the honest answer to “is anything stuck?”.
curl -H "Authorization: Bearer $ALGOUM_API_KEY" "https://api.algoum.de/v1/status"Errors
Errors carry no data. They return an error object with a stable code to branch on, a message meant for a human, and the request_id.
| Status | Code | Meaning |
|---|---|---|
400 | invalid_parameter | A parameter is missing, malformed or out of range. The message names it. |
401 | unauthorized | The API key is missing or invalid. |
404 | not_found | The requested record does not exist. |
429 | — | Rate limit exceeded. Rejected before it reaches the API, so the body is plain text. Wait the seconds in Retry-After. |
500 | internal_error | Unexpected error on our side. The cause is in our logs, keyed by request_id. |
503 | — | A prerequisite is not ready yet, for example the ticker universe is still loading. Retrying later is worthwhile. |
Rate limit
Requests are limited per client: roughly 100 requests per second, with an extra allowance of 50 requests for short bursts. Going over it answers 429 with a Retry-After header that names the seconds to wait. That rejection happens in front of the API, so its body is plain text rather than the JSON error body, and it has no request_id. Wait as long as Retry-After says, then retry. Pricing and limits sums up what your key gives you.
Every record names its source
Records carry filing_id and source_url, pointing at the original SEC document they were derived from. Nothing here is estimated or inferred, and you can always check a value against the filing itself. Data sources lists which forms those documents are and what each one reports.