> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mkk.celebi.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Documents: Understanding Parsed Fund Disclosures

> Documents are parsed MKK/VYK PDF disclosure reports containing structured line item values, portfolio entries, and optional raw text and table data.

Documents are the core data objects in the MKK Structured Data API. Each document represents a single parsed PDF disclosure report filed by an investment fund with MKK or VYK. When you fetch a document, you get structured financial data extracted from that report — including key-value line items, portfolio holdings tables, and metadata that links back to the original filing.

## What a document contains

Every document belongs to a fund and covers a single reporting `period`. The API parses each PDF and exposes the extracted data in two complementary forms:

* **`line_item_values`** — structured key-value pairs mapping canonical financial metrics (e.g., net asset value, number of units) to their extracted values for that document. These are the primary way to access normalized, comparable data across funds and periods.
* **`portfolio_entries`** — normalized rows from the fund's holdings table, each representing a single security position with fields like ISIN, market value, and portfolio weight.

The document also exposes `portfolio_rows` — the raw table rows as parsed from the PDF, preserving the original column structure. Use `portfolio_rows` when you need the unmodified tabular data before normalization.

## Key fields

| Field                | Description                                              |
| -------------------- | -------------------------------------------------------- |
| `id`                 | Numeric document ID                                      |
| `disclosure_index`   | MKK's own reference number for this filing               |
| `fund_code`          | The fund this document belongs to                        |
| `period`             | Reporting period (e.g., `"2023-Q3"`)                     |
| `document_type`      | Type of disclosure (e.g., quarterly, annual)             |
| `report_date`        | Date the report was filed                                |
| `management_company` | Name of the fund's management company                    |
| `page_count`         | Total pages in the source PDF                            |
| `parsed_pages`       | Number of pages successfully parsed                      |
| `pdf_url`            | Direct URL to the source PDF                             |
| `kap_url`            | Link to the filing on the KAP public disclosure platform |
| `kap_file_url`       | Direct file link on KAP                                  |

## KAP links

`kap_url` and `kap_file_url` point to the original filing on the KAP (Public Disclosure Platform) system, which is Turkey's official public filing portal. These links let you verify the source document or retrieve the original PDF directly from the filing authority. `kap_url` links to the filing's detail page, while `kap_file_url` links directly to the downloadable file.

## Accessing the source PDF

You can download the source PDF for any document using the dedicated endpoint:

```bash theme={null}
GET https://mkk-roan.vercel.app/api/documents/{docId}/pdf
```

This redirects to the `pdf_url` stored for the document.

## Raw text and tables

By default, document responses omit raw text and raw table data to keep payloads small. Add `include_raw=true` to include them:

```bash theme={null}
GET https://mkk-roan.vercel.app/api/documents/42?include_raw=true
```

With `include_raw=true`, the response includes:

* **`raw_text`** — the full extracted text from the PDF, page by page
* **`tables`** — raw table structures parsed from each page

<Note>
  Raw text and table data can significantly increase response size. Only request `include_raw=true` when you need to inspect or reprocess the underlying PDF content.
</Note>

## Example requests

<CodeGroup>
  ```bash List documents theme={null}
  curl https://mkk-roan.vercel.app/api/documents
  ```

  ```bash Get a document by ID theme={null}
  curl https://mkk-roan.vercel.app/api/documents/42
  ```

  ```bash Get a document by disclosure index theme={null}
  curl https://mkk-roan.vercel.app/api/disclosures/FCH2023Q3
  ```
</CodeGroup>

### Example response: GET /documents/42

```json theme={null}
{
  "id": 42,
  "disclosure_index": "FCH2023Q3",
  "fund_code": "OJB",
  "file_name": "ojb_2023q3.pdf",
  "pdf_url": "https://mkk-roan.vercel.app/api/documents/42/pdf",
  "kap_url": "https://www.kap.org.tr/tr/Bildirim/1023456",
  "kap_file_url": "https://www.kap.org.tr/tr/BildirimPdf/1023456",
  "page_count": 12,
  "parsed_pages": 12,
  "document_type": "quarterly",
  "period": "2023-Q3",
  "report_date": "2023-10-15",
  "management_company": "Example Portföy A.Ş.",
  "line_item_values": [...],
  "portfolio_entries": [...],
  "totals": {...}
}
```

## Filtering documents

You can filter documents by fund when listing:

```bash theme={null}
GET https://mkk-roan.vercel.app/api/documents?fund_code=OJB
```