/api/external/v2/deals/{deal_id}/index/taxonomyReturn the Deal Index navtree used to resolve citation ?node= values
Purpose. Return the Deal Index sidebar navtree. Match a Search Index fact via category_id and ref_id / entity_ref. Do not invent a node when no row matches. Prefer sidebar_node_id on the search hit; this tree is the backup walk.
Visibility: user-facing. This is a public External API v2 endpoint. REST integrators and the Lev MCP tool list_deal_index_taxonomy call it. It does not return facts, values, or source documents.
Auth / scopes. Requires the deals:read scope. The deal must be readable by the authenticated user.
The full tree is returned in one response. It is not paged — extra query params such as MCP limit are ignored. Optional repeatable include filters node types only (CATEGORY, SUB_CATEGORY, METRIC_GROUP, ENTITY_GROUP). Omit include or send an empty value to get every node.
Selectable citation targets are SUB_CATEGORY, ENTITY_GROUP, or a drilldown METRIC_GROUP. Never use a CATEGORY id as ?node=. A non-drilldown METRIC_GROUP should use its parent SUB_CATEGORY id.
deal_idintegerrequiredincludestring[]curl "https://api.lev.com/api/external/v2/deals/101/index/taxonomy" \
-H "Authorization: Bearer YOUR_API_KEY"Filter to subcategories and entity groups:
curl "https://api.lev.com/api/external/v2/deals/101/index/taxonomy?include=SUB_CATEGORY&include=ENTITY_GROUP" \
-H "Authorization: Bearer YOUR_API_KEY"Response (200):
{
"request_id": "b8c9d0e1-f2a3-4567-bcde-678901234567",
"timestamp": "2026-10-19T15:30:45Z",
"data": [
{
"id": "cat-financials",
"parent_id": null,
"type": "CATEGORY",
"label": "Deal Financials",
"value": "deal_financials",
"order": 1,
"icon": "chart",
"category_id": 5,
"dashboard_type": null,
"ref_id": null
},
{
"id": "sub-1",
"parent_id": "eg-property-690",
"type": "SUB_CATEGORY",
"label": "NOI",
"value": "noi",
"order": 2,
"icon": null,
"category_id": 5,
"dashboard_type": "key_values",
"ref_id": null
},
{
"id": "eg-property-690",
"parent_id": "cat-financials",
"type": "ENTITY_GROUP",
"label": "2727 Cedar Springs Road",
"value": null,
"order": 1,
"icon": null,
"category_id": null,
"dashboard_type": null,
"ref_id": "property:690"
}
],
"pagination": {
"total": 3,
"limit": 3,
"offset": 0,
"has_more": false
}
}For selectable rows (SUB_CATEGORY, ENTITY_GROUP, or a drilldown METRIC_GROUP), id is the portal ?node= value. Do not use a CATEGORY id as ?node=. A non-drilldown METRIC_GROUP should use its parent SUB_CATEGORY id. POST /index/search returns that id on each fact as sidebar_node_id (null when the walk would not land on a selectable row). Pass nodes through. Do not invent a node if the walk misses.
The MCP wrapper list_deal_index_taxonomy calls this same endpoint and returns taxonomy_nodes. See MCP tools.
unauthorizedforbiddennot_foundservice_unavailable