Build

Index taxonomy

Return the Deal Index taxonomy tree for a deal. Use a node's id as the portal ?node= only for selectable rows. Prefer sidebar_node_id on Search Index hits; use this tree only when you need to walk it.

Updated October 2026
GET/api/external/v2/deals/{deal_id}/index/taxonomy

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

Path parameters
deal_idintegerrequired
The deal ID
Query parameters
includestring[]
Optional repeatable node-type filter: CATEGORY, SUB_CATEGORY, METRIC_GROUP, or ENTITY_GROUP. Omit or empty returns the full tree. Serialized as repeated query keys (?include=SUB_CATEGORY&include=ENTITY_GROUP). This is a taxonomy type filter, not deal ?include=financials.
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.

401unauthorized
Authentication required— Missing or invalid Authorization header
403forbidden
Missing required scope: deals:read— The credential does not include the deals:read scope
404not_found
Deal not found— The deal_id doesn't exist or isn't accessible to the authenticated user
503service_unavailable
Deal taxonomy is temporarily unavailable. Try again shortly.— The taxonomy service is unavailable or returned a non-list payload
More in this section