Line Items Endpoints: MKK API Reference Guide

The line items endpoints expose two distinct but related concepts. A line item is a canonical definition in the MKK schema — a named metric or text field with a stable slug (e.g., total-net-assets) that appears across many documents. A line item value is a single extracted instance of that metric from a specific document: the actual number or text pulled from a fund’s disclosure for a given reporting period. Use the line items endpoints to explore the schema, and use the line item values endpoints to query the extracted data.

Endpoints

Method	Path	Description
`GET`	`/line-items`	List canonical line item definitions
`GET`	`/line-items/{lineItemIdOrSlug}`	Retrieve a single line item with its values
`GET`	`/line-item-values`	Query extracted line item values across all documents
`GET`	`/key-values`	Alias for `GET /line-item-values`

Base URL: https://mkk-roan.vercel.app/api

GET /key-values is an exact alias for GET /line-item-values. Both endpoints accept the same parameters and return the same response shape. You can use either path interchangeably.

GET /line-items

Returns a paginated list of canonical line item definitions with aggregate statistics.

Query parameters

kind

string

Filter by line item kind. Accepted values: metric (numeric values) or text (string values).

section_id

string

Filter by canonical section slug (e.g., net-asset-value).

fund_id

string

Filter to line items that appear in documents for the fund with this internal ID.

fund_code

string

Filter to line items that appear in documents for the fund with this fund code (e.g., OJB).

string

Free-text search against line item names.

limit

integer

default:"50"

Maximum number of results to return. Accepts values from 1 to 500.

offset

integer

default:"0"

Number of results to skip. Use with limit to paginate.

Response schema

total

integer

required

Total matching line items.

limit

integer

required

Effective limit applied.

offset

integer

required

Effective offset applied.

line_items

LineItem[]

required

Array of canonical line item objects.

Show LineItem properties

string

required

Internal database identifier.

slug

string

required

URL-safe canonical slug (e.g., total-net-assets). Use this as the lineItemIdOrSlug path parameter or as the line_item_slug query filter.

name

string

required

Human-readable canonical name.

sectionId

string

required

Canonical section slug this line item belongs to.

sectionName

string

required

Human-readable section name.

section

object

required

Nested section object with full section metadata.

unit

string

Unit of measure (e.g., TRY, %, days). May be empty for text-kind items.

kind

string

required

Either metric (numeric) or text.

value_count

integer

required

Total number of extracted values for this line item across all documents.

fund_count

integer

required

Number of distinct funds that have at least one value for this line item.

document_count

integer

required

Number of documents containing at least one value for this line item.

values

LineItemValue[]

Array of extracted values. Only populated on the detail endpoint or when values are explicitly requested.

Example requests

curl https://mkk-roan.vercel.app/api/line-items

Example response

200

{
  "total": 198,
  "limit": 50,
  "offset": 0,
  "line_items": [
    {
      "id": "li_001",
      "slug": "total-net-assets",
      "name": "Total Net Assets",
      "sectionId": "net-asset-value",
      "sectionName": "Net Asset Value",
      "section": { "id": "sec_01", "sectionId": "net-asset-value", "name": "Net Asset Value" },
      "unit": "TRY",
      "kind": "metric",
      "value_count": 4412,
      "fund_count": 289,
      "document_count": 4412
    }
  ]
}

GET /line-items/

Returns a single line item definition together with its extracted values, with optional filtering by fund and period.

Path parameters

lineItemIdOrSlug

string

required

Either the internal ID or the canonical slug of the line item (e.g., total-net-assets).

Query parameters

fund_id

string

Filter returned values to those from documents belonging to the fund with this internal ID.

fund_code

string

Filter returned values to those from documents belonging to the fund with this fund code (e.g., OJB).

period

string

Filter returned values to those from documents for this reporting period (YYYY-MM).

limit

integer

default:"500"

Maximum number of values to return in the nested values array.

Error responses

Status	Description
`404`	No line item with the given ID or slug exists.

Example requests

curl https://mkk-roan.vercel.app/api/line-items/total-net-assets

GET /line-item-values

Queries extracted line item values directly, without needing to navigate through line item definitions first. This is the primary endpoint for time-series and cross-fund data extraction.

Query parameters

fund_id

string

Filter to values from documents belonging to the fund with this internal ID.

fund_code

string

Filter to values from documents belonging to the fund with this fund code (e.g., OJB).

period

string

Filter to values from documents for this reporting period (YYYY-MM).

section_id

string

Filter to values belonging to the canonical section with this slug.

line_item_slug

string

Filter to values for the canonical line item with this slug (e.g., total-net-assets).

string

Free-text search across value labels and line item names.

label

string

Filter by the raw label as it appeared in the source document. Useful for investigating mapping quality.

limit

integer

default:"100"

Maximum number of values to return. Accepts values from 1 to 500.

Response schema

line_item_values

LineItemValue[]

required

Array of extracted line item value objects.

Show LineItemValue properties

string

required

Internal database identifier for this value.

document_id

integer

required

ID of the document this value was extracted from.

disclosure_index

string

required

MKK disclosure index of the source document.

file_name

string

required

File name of the source document.

fund_code

string

required

Fund code of the source document.

fund_title

string

required

Full fund name.

period

string

required

Reporting period (YYYY-MM).

line_item_id

string

required

Internal ID of the canonical line item.

line_item_slug

string

required

Canonical slug of the line item.

line_item_name

string

required

Canonical name of the line item.

sectionId

string

required

Canonical section slug.

sectionName

string

required

Canonical section name.

canonical_section

string

required

Canonical section slug (same as sectionId).

kind

string

required

metric or text.

raw_section

string

required

The raw section heading as it appeared in the source PDF before normalization.

raw_label

string

required

The raw label text as it appeared in the source PDF before normalization.

value

string

required

Extracted value as a string (always present regardless of kind).

numeric_value

number

Parsed numeric value. Present for metric-kind items when the value could be successfully parsed. null on parse failure.

unit

string

Unit of measure (e.g., TRY, %).

source

string

required

Extraction source (e.g., table, text).

mapping_method

string

required

How this raw label was mapped to its canonical line item. Common values include exact (exact string match), fuzzy (fuzzy string match), manual (human-reviewed mapping), and model (ML-based mapping).

mapping_confidence

number

required

Confidence score for the mapping, from 0.0 (uncertain) to 1.0 (certain). Values mapped with exact or manual methods typically have confidence 1.0. Use this field to filter out low-confidence mappings in analytical workflows.

Example requests

curl "https://mkk-roan.vercel.app/api/line-item-values?fund_code=OJB&period=2023-06"

Example response

200

{
  "line_item_values": [
    {
      "id": "lv_00001",
      "document_id": 1042,
      "disclosure_index": "2023-TR-00012345",
      "file_name": "OJB_202306.pdf",
      "fund_code": "OJB",
      "fund_title": "Oyak Jinsi Bono Fonu",
      "period": "2023-06",
      "line_item_id": "li_001",
      "line_item_slug": "total-net-assets",
      "line_item_name": "Total Net Assets",
      "sectionId": "net-asset-value",
      "sectionName": "Net Asset Value",
      "canonical_section": "net-asset-value",
      "kind": "metric",
      "raw_section": "FON TOPLAM DEĞERİ VE NET VARLIK DEĞERİ",
      "raw_label": "Toplam Net Varlık Değeri",
      "value": "1234567890.50",
      "numeric_value": 1234567890.5,
      "unit": "TRY",
      "source": "table",
      "mapping_method": "exact",
      "mapping_confidence": 1.0
    }
  ]
}

System

Funds & Documents

Financial Data

Exports & Quality

Line Items Endpoints: MKK API Reference Guide

Endpoints

GET /line-items

Query parameters

Response schema

Example requests

Example response

GET /line-items/

Path parameters

Query parameters

Error responses

Example requests

GET /line-item-values

Query parameters

Response schema

Example requests

Example response

System

Funds & Documents

Financial Data

Exports & Quality

Documentation Index

​Endpoints

​GET /line-items

​Query parameters

​Response schema

​Example requests

​Example response

​GET /line-items/

​Path parameters

​Query parameters

​Error responses

​Example requests

​GET /line-item-values

​Query parameters

​Response schema

​Example requests

​Example response

Endpoints

GET /line-items

Query parameters

Response schema

Example requests

Example response

GET /line-items/

Path parameters

Query parameters

Error responses

Example requests

GET /line-item-values

Query parameters

Response schema

Example requests

Example response