> ## 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.

# Line Items: Querying Canonical Financial Metrics

> Line items are canonical financial metrics and text fields extracted from fund reports, identified by stable slugs and organized into report sections.

Line items are the building blocks of structured financial data in the MKK API. Each line item defines a canonical metric or text field that can appear across many fund reports — things like net asset value, number of circulating units, or fund manager name. By mapping raw PDF labels to these canonical definitions, the API lets you compare the same metric across different funds and reporting periods using a single stable identifier.

## Kinds of line items

Every line item has a `kind` field that indicates what type of value it holds:

* **`metric`** — a numeric measurement (e.g., net asset value, total assets). These line items have a `unit` field (e.g., `"TRY"`, `"units"`) and populate the `numeric_value` field in their values.
* **`text`** — a descriptive or categorical value (e.g., fund manager name, investment strategy description). These line items have no unit and store their data in the string `value` field.

## Slugs as stable identifiers

Each line item is identified by a `slug` — a kebab-case string like `"net-asset-value"` or `"number-of-units"`. Slugs are stable across API versions and safe to hard-code in your application. Use the slug to fetch a specific line item or to filter values:

```bash theme={null}
GET https://mkk-roan.vercel.app/api/line-items/net-asset-value
```

## Sections

Line items are organized into canonical report sections (e.g., `"fund-information"`, `"balance-sheet"`). The `sectionId` on a line item tells you which section it belongs to. Sections have a `sort_order` that reflects their order in a standard MKK disclosure report.

You can browse available sections at `/sections`, optionally filtered by fund:

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

## Line item values

A `LineItemValue` is the actual extracted value for a specific line item in a specific document. Where the line item definition is the schema, the value is the data. Each value records:

| Field                | Description                                              |
| -------------------- | -------------------------------------------------------- |
| `document_id`        | The document this value was extracted from               |
| `disclosure_index`   | The MKK disclosure reference                             |
| `fund_code`          | The fund the document belongs to                         |
| `period`             | The reporting period                                     |
| `line_item_slug`     | Slug of the parent line item                             |
| `raw_label`          | The original label text as it appeared in the PDF        |
| `value`              | Extracted value as a string                              |
| `numeric_value`      | Parsed numeric value (for `metric` kind)                 |
| `unit`               | Unit of measurement                                      |
| `mapping_method`     | How the raw label was matched to the canonical line item |
| `mapping_confidence` | Confidence score for the mapping (0–1)                   |

## Mapping method and confidence

Because MKK PDF reports are not perfectly consistent across funds or periods, the API uses a matching process to map raw PDF labels to canonical line items. The `mapping_method` tells you how the match was made (e.g., exact string match, fuzzy match, or ML-based inference), and `mapping_confidence` gives you a 0–1 score indicating how certain the system is about that match.

<Warning>
  Values with a low `mapping_confidence` should be treated with extra care. A score below 0.7 may indicate that the raw label was ambiguous or unusual — verify against the source PDF using the document's `pdf_url` or `kap_file_url` when precision is critical.
</Warning>

The `raw_label` field preserves the original text from the PDF so you can inspect what the parser actually found.

## Example requests

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

  ```bash Get a specific line item theme={null}
  curl https://mkk-roan.vercel.app/api/line-items/net-asset-value
  ```

  ```bash Get values for a fund and period theme={null}
  curl "https://mkk-roan.vercel.app/api/line-item-values?fund_code=OJB&period=2023-Q3"
  ```
</CodeGroup>

### Example response: GET /line-items/net-asset-value

```json theme={null}
{
  "id": 7,
  "slug": "net-asset-value",
  "name": "Net Asset Value",
  "sectionId": "balance-sheet",
  "unit": "TRY",
  "kind": "metric",
  "value_count": 1240,
  "fund_count": 38,
  "document_count": 312
}
```

### Example LineItemValue

```json theme={null}
{
  "document_id": 42,
  "disclosure_index": "FCH2023Q3",
  "fund_code": "OJB",
  "period": "2023-Q3",
  "line_item_slug": "net-asset-value",
  "raw_label": "Fon Toplam Değeri",
  "value": "154320000.00",
  "numeric_value": 154320000.00,
  "unit": "TRY",
  "mapping_method": "exact",
  "mapping_confidence": 1.0
}
```

<Note>
  The `/key-values` endpoint is an alias for `/line-item-values` and accepts the same query parameters. Both paths return identical responses.
</Note>