# Documents

List company reports, search their content and read paragraphs or tables.

Source: <https://docs.finbar.com/api-mcp/documents>

A **document** is a company report. Each document has a `document_id` and
contains readable **items**: paragraphs and tables, each with its own ID.
Search locates items within documents; reading an item returns its content.

All endpoints on this page require `documents:read`. First
[find a company](https://docs.finbar.com/api-mcp/entities.md) and set `ENTITY_ID` to its `entity_id`.
The examples use an [access token](https://docs.finbar.com/api-mcp/authentication.md) as `ACCESS_TOKEN`.

## List reports

```text
GET /v1/entities/{entity_id}/documents
```

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

| Query parameter              | Meaning                                                                    |
| ---------------------------- | -------------------------------------------------------------------------- |
| `document_types`             | Filter by document type; `FULL_FINANCIAL_REPORT` selects financial reports |
| `start_period`, `end_period` | Inclusive reporting-period bounds, such as `2024Y` and `2025Y`             |
| `tags`                       | Filter by document tags                                                    |
| `limit`                      | Reports per page, from 1 to 100; default 50                                |
| `cursor`                     | Continuation value from `next_cursor`                                      |

The `documents` array includes document IDs, types and reporting periods.
Results are ordered by report date, most recent first. Period filters refer
to the [period covered by a report](https://docs.finbar.com/api-mcp/periods.md#document-periods), not
its publication date.

**GET /v1/entities/{entity\_id}/documents — 200 response**

Example response. IDs and values are illustrative.

```json
{
  "documents": [
    {
      "document_id": "D-d15ec8e059d94a2f8aa352025f57f7bb",
      "entity_id": "O-03049bdc0cb94012b761a4c3046c2a2d",
      "period": {
        "year": 2025,
        "period_type": "Y",
        "period": 0
      },
      "publish_date": "2025-10-31T00:00:00Z",
      "report_date": "2025-09-27T00:00:00Z",
      "status": "PARSED",
      "type": "FULL_FINANCIAL_REPORT",
      "tag": "20F"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJxIjoiLi4uIn0"
}
```

## Search report content

```text
POST /v1/document-search
```

Search all available reports for a company:

```bash
curl --fail-with-body --silent --show-error \
  'https://api.finbar.com/v1/document-search' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{\"entity_id\":\"$ENTITY_ID\",\"query\":\"revenue growth\",\"limit\":5}"
```

| Body field                   | Meaning                                                                 |
| ---------------------------- | ----------------------------------------------------------------------- |
| `query`                      | Required search text                                                    |
| `entity_id` or `document_id` | Required search target; supply exactly one                              |
| `start_period`, `end_period` | Optional inclusive reporting-period bounds; only valid with `entity_id` |
| `limit`                      | Matches per page, from 1 to 20; default 5                               |
| `cursor`                     | Continuation value from `next_cursor`                                   |

To search one report, replace `entity_id` with its `document_id`. The `results`
array contains matching paragraphs and tables. Each has an `id`, `document_id`
and `preview`. A preview is an excerpt; read the matching item before using it
as evidence for an answer.

## Read a paragraph or table

```text
GET /v1/document-items/{item_id}
```

Set `ITEM_ID` to a search result's `id` or a dataset source's `item_id`:

```bash
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 rendered text or table content in each
chunk's `content` field. A **chunk** is one bounded piece of content returned
by a document read. `is_truncated: true` means content has been shortened.

For a large table, the optional `table_subslice` query parameter selects a
smaller range while retaining header context. For example, `R0C0:R4C3` selects
rows 0–4 and columns 0–3; indices start at zero. Use a table ID for this
parameter; if a paragraph links to a table, read its returned `table_id`
directly. `raw_data=true` requests raw table values where available.

## Read through a report

```text
GET /v1/documents/{document_id}/chunks
```

Set `DOCUMENT_ID` to an ID from the document list:

```bash
curl --fail-with-body --silent --show-error --get \
  "https://api.finbar.com/v1/documents/$DOCUMENT_ID/chunks" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'start_index=0' \
  --data-urlencode 'limit=5'
```

`start_index` is the zero-based paragraph position at which to start reading.
`limit` is required and accepts 1–10 chunks. To continue, send `cursor` with
the returned `next_cursor` in place of `start_index`, keeping `limit`.

For lists and searches, also follow `next_cursor` until it is absent. Keep the
same target and filters. See [pagination](https://docs.finbar.com/api-mcp/errors.md#pagination) for the
common pattern.