Build

Search Index

Search canonical indexed deal facts and their source documents in the Lev API. Each hit includes sidebar_node_id, the Deal Index portal ?node= value.

Updated October 2026
POST/api/external/v2/deals/{deal_id}/index/search

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

Path parameters
deal_idintegerrequired
The deal ID
Request body
contextstring
Natural-language search context (1-4000 characters after trim). Required when sot_ids is omitted. Be specific about the metric or topic you want.
sot_idsstring[]
Prefixed SOT ids for an exact lookup (for example d:123 or a:17544:property:2561). Each item must be a prefixed id — strip blanks before sending. The server also drops blank items, then validates the rest; an empty list is treated as omitted. When set, embeddings are skipped and min_score is forced to 0. At least one of context or sot_ids is required.
min_scorenumber
Minimum similarity threshold from 0 to 1. Defaults to 0.3. Ignored when sot_ids is set.
limitinteger
Maximum ranked facts to return. Defaults to 20 and is clamped to 1-200. For an exact lookup, set limit to the number of sot_ids (max 200) and batch any further ids into another call.
include_signed_urlsboolean
When true, document-backed source records may include short-lived signed URLs for inspection or download.
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 '{
    "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.

422validation_error
Provide at least one of context or sot_ids— The request body omits both context and sot_ids, sends only whitespace or empty sot_ids, or includes a sot_ids item that is not a prefixed identifier such as d:123
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 data search is temporarily unavailable. Try again shortly.— The indexed-data search service is unavailable
More in this section