/api/external/v2/deals/{deal_id}/index/searchSearch canonical indexed deal facts by natural-language context or prefixed sot id
Purpose. Use Index search when you need source-backed facts that may live in deal attachments or normalized underwriting data. It complements GET /deals/{deal_id}: use GET /deals/{deal_id} for structured deal fields, then use Index search for targeted questions about metrics, loan terms, proceeds, rent roll, occupancy, sponsor background, valuations, capex, dates, and source documents.
Visibility: user-facing. This is a public External API v2 endpoint. REST integrators, the Lev MCP tool search_deal_index, and end-user agents all call it.
Auth / scopes. Requires the deals:read scope. The deal must be readable by the authenticated user. MCP callers inherit the signed-in Lev user's permissions; they do not get a separate Index scope.
The endpoint searches Metric SOT / Index data for one deal. It does not return an exhaustive full Index export. A single call returns at most 200 facts and takes no offset.
Pass at least one of context or sot_ids. context is a semantic search: Lev embeds the phrase and ranks facts by similarity. sot_ids is an exact lookup of prefixed ids you already have (from a prior search hit's id, or from a citation URL sotId). When sot_ids is set, embeddings are skipped and min_score is forced to 0.
Each result always includes sidebar_node_id: the Deal Index portal ?node= value for that fact, using the same selectable-row rule as the sidebar (SUB_CATEGORY, ENTITY_GROUP, or a drilldown METRIC_GROUP; a non-drilldown METRIC_GROUP uses its parent subcategory). The value is null when no selectable sidebar row matches. Do not invent a node from category_id or entity_ref. Prefer sidebar_node_id on the search hit. Call Index taxonomy only when you need the full navtree.
deal_idintegerrequiredcontextstringsot_idsstring[]min_scorenumberlimitintegerinclude_signed_urlsbooleancurl -X POST "https://api.lev.com/api/external/v2/deals/101/index/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"context": "in-place NOI and source documents",
"min_score": 0.3,
"limit": 5,
"include_signed_urls": false
}'Response (200):
{
"request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"timestamp": "2026-05-06T15:30:45Z",
"data": [
{
"id": "1",
"sot_id": 1,
"metric_key": "deal_financials.in_place_noi",
"metric_id": 42,
"metric_label": "In-place NOI",
"value_text": "$1,250,000",
"value_type": "currency",
"context": "The appraisal reports trailing twelve month NOI.",
"summary": "In-place NOI is $1.25M based on the appraisal.",
"period_type": "point_in_time",
"period_value": null,
"entity_type": "deal",
"entity_id": null,
"entity_ref": "deal:123",
"group_ref": null,
"category_id": 5,
"sidebar_node_id": "sub-1",
"category_label": "Deal Financials",
"needs_review": false,
"score": 0.87,
"source": {
"type": "document",
"document_id": 99,
"document_type": "appraisal",
"file_name": "appraisal.pdf",
"file_extension": ".pdf",
"pages": [3, 12],
"observation_count": 3,
"signed_url": null
}
}
],
"pagination": {
"total": 1,
"limit": 5,
"offset": 0,
"has_more": false
}
}sidebar_node_id is always present on each row. Copy it into a citation URL as node when it is a non-empty string. When it is null, omit node — do not invent one.
Exact lookup example — refresh cited values you already have ids for:
curl -X POST "https://api.lev.com/api/external/v2/deals/101/index/search" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sot_ids": ["d:5362", "a:17544:property:2561"],
"limit": 2
}'When include_signed_urls=true, document-backed results may include source.signed_url. Signing failures are non-fatal: the result stays in the response with source.signed_url=null and a typed source.signed_url_error such as signing_failed, missing_document_id, or invalid_document_id.
The MCP wrapper search_deal_index calls this same endpoint. It copies REST sidebar_node_id onto the tool result as sidebarNodeId and onto citation node, and omits node when the id is null, empty, or the literal "None" sentinel. See MCP tools.
validation_errorunauthorizedforbiddennot_foundservice_unavailable