Companies and documents

For an AI assistant, start with a request such as:

Use Finbar to find Apple, list its recent annual reports and find the discussion of revenue growth. Include the source references.

For the API, first obtain an access token with company and document read permissions. The examples below use that token as ACCESS_TOKEN.

1. Find the company

Search by name or ticker using GET /v1/entities?q=Apple. Choose a match from the entities array and copy its entity_id into ENTITY_ID. Use returned IDs in later requests; a company name or ticker is not an ID.

2. List its documents

curl --fail-with-body --silent --show-error --get \
  "https://api.finbar.com/v1/entities/$ENTITY_ID/documents" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'limit=5'

The documents array includes each document's document_id, type and reporting period. Results are ordered by report date, with the most recent first.

Optional filters include document_types, start_period and end_period. For example, document_types=FULL_FINANCIAL_REPORT selects financial reports; start_period=2024Y and end_period=2025Y set inclusive reporting-period bounds. These are reporting periods, not publication dates.

3. Search the content

Send this JSON to POST https://api.finbar.com/v1/document-search, with the same Authorization header and Content-Type: application/json. Replace YOUR_ENTITY_ID with the company ID:

{
  "entity_id": "YOUR_ENTITY_ID",
  "query": "revenue growth",
  "limit": 5
}

To search one document, replace entity_id with document_id. Supply one of these fields, not both.

The results array contains paragraph and table matches, each with an id, document_id and a short preview. Read the matching item for more context.

4. Read a source item

Set ITEM_ID to the id of a search result:

curl --fail-with-body --silent --show-error \
  "https://api.finbar.com/v1/document-items/$ITEM_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

The response's chunks array contains the item text or table content. To read through a document instead, use GET /v1/documents/{document_id}/chunks?start_index=0&limit=5. A document read returns up to 10 items per request. is_truncated, when true, means some content has been shortened.

Keep the returned document and item IDs with your results so you can refer back to the sources.

Continue through results

When a response includes next_cursor, repeat the request with that value in cursor. Keep the same search and filters. For document reads, use cursor in place of start_index. Stop when next_cursor is absent.

Equivalent MCP tools

An assistant can carry out these steps using the same returned IDs. MCP also provides get_market_data for available price history and market information.