Skip to main content

​
Which version to use

Each resource has one current endpoint. Older versions stay available, so existing integrations keep working.

​
v1 document by ID

GET /api/v1/documents/{id} is kept for older integrations. Compared with v2, it:
  • returns formType and tickers instead of secFormType and companyTickers, and has no fiscalPeriod, language or companyId;
  • returns legacy category codes: renamed categories map to their old code, and categories that didn’t exist before are returned as other.
Every other endpoint returns the current codes listed in Document Coverage. The documentCategories filter accepts both current and legacy codes.

​
Pagination

To read all results, request pages with the same filters and increasing offset (0, limit, 2 × limit, …) until a page returns fewer than limit items. Results have a stable order: companies by name, documents by date (newest first by default), with ties broken by ID.

​
Tickers

Ticker filters (tickers on /companies/list, companyTickers on /documents/list) accept tickers in the form the API returns them:
  • With an exchange suffix, such as STO.AX or ITX.MC, to match one listing.
  • Without a suffix, such as STO or AAPL, to match that symbol on every exchange. A short symbol can match companies listed on different exchanges, so prefer the suffixed form.
  • Symbols that contain a dot work as returned, for example BRK.B or BRK.B.US.
Matching is case-sensitive: use upper case as in the API’s responses. Country codes (countries) are matched in any case.

​
Document IDs

Use the id from /documents/list, from documentMetadata.id in chunks and agent sources, or from a webhook payload, with GET /api/v2/documents/{id}. They identify the same document across endpoints. originalFileUrl and markdownFileUrl are signed links that expire one hour after the request. Download the files within that hour, or request the document again for fresh links instead of storing them. When a document has no Markdown version yet, markdownFileUrl is an empty string.

​
Limits and credits

  • Requests over your organization’s rate limit receive 429. Wait and retry.
  • Each endpoint has a price per call in API credits; when your organization runs out of credits, requests receive 402. Check usage in the API Dashboard.
  • Requests that take longer than about 15 seconds are cut off with 504. This mainly affects text searches (query on /documents/list) for very common words across all companies: add a filter such as companyTickers or documentCategories.