---
title: "Search Deal Index"
method: POST
path: "/api/external/v2/deals/{deal_id}/index/search"
tags: ["external-v2-deals"]
---

# Search Deal Index

`POST /api/external/v2/deals/{deal_id}/index/search`

## Request

- Base URL: `https://api.lev.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.lev.com/api/external/v2/deals/{deal_id}/index/search`
- Auth: none declared

Search canonical indexed deal facts, or look them up by prefixed sot id.

Context search embeds the query. When ``sot_ids`` is set the lookup is
exact: embeddings are skipped and ``min_score`` is forced to 0, matching
GraphQL ``searchSotByEmbeddings(dealId, sotIds, minScore: 0)``.

## Path parameters

- `deal_id` integer, required

## Request body

- DealIndexSearchRequest: POST /api/external/v2/deals/<id>/index/search request body. ``context`` is a semantic search. ``sot_ids`` is an exact lookup of the prefixed ids already stored on citation links. At least one is required.
  - `context` string, nullable: Natural-language deal-data search context. Required when sot_ids is omitted.
  - `sot_ids` string[], nullable: Prefixed SOT ids for an exact lookup (e.g. 'd:123', 'a:17544:property:2561'). When set, embeddings are skipped.
  - `min_score` number: Minimum cosine similarity threshold (0-1). Ignored when sot_ids is set.
  - `limit` integer: Maximum ranked facts to return (1-200, clamped).
  - `include_signed_urls` boolean: When true, include time-limited signed URLs for document-backed source attachments.

## Response `200`

Successful Response

- DealIndexSearchListResponse: OpenAPI schema for POST /api/external/v2/deals/<id>/index/search.
  - `request_id` string, required
  - `timestamp` string, required
  - `data` DealIndexSearchResultResponse[], required
    - `id` string, nullable
    - `sot_id` integer, nullable
    - `metric_key` string, nullable
    - `metric_id` integer, nullable
    - `metric_label` string, nullable
    - `value_text` string, nullable
    - `value_type` string, nullable
    - `context` string, nullable
    - `summary` string, nullable
    - `period_type` string, nullable
    - `period_value` string, nullable
    - `entity_type` string, nullable
    - `entity_id` integer, nullable
    - `entity_ref` string, nullable
    - `group_ref` string, nullable
    - `category_id` integer, nullable
    - `sidebar_node_id` string, nullable
    - `category_label` string, nullable
    - `needs_review` boolean, nullable: Always null; superseded by distinct_value_count / resolved_at.
    - `distinct_value_count` integer, nullable
    - `differing_value_count` integer, nullable
    - `resolved_at` string, nullable
    - `has_differing_values` boolean, nullable
    - `editable` boolean, nullable
    - `score` number, nullable
    - `source` DealIndexSearchSourceResponse, required: Source/provenance metadata for a ranked deal-data fact.
      - `type` string, nullable, required
      - `document_id` integer, nullable
      - `document_type` string, nullable
      - `file_name` string, nullable
      - `file_extension` string, nullable
      - `pages` integer[], nullable
      - `observation_count` integer, nullable
      - `signed_url` string, nullable
      - `signed_url_error` string, nullable
  - `pagination` unknown, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-02** `4cfc778338ce`: 1 info
  - added the optional property `data/items/sidebar_node_id` to the response with the `200` status
- **2026-09-25** `04c60da269dc`: 4 info
  - added the new optional request property `sot_ids`
  - the request property `context` became optional
  - request property `context` list-of-types was widened by adding types `null` to media type `application/json`
  - the `context` request property's minLength was decreased from `1` to `0`
- **2026-09-01** `78060050da81`: 1 info
  - added the optional property `data/items/differing_value_count` to the response with the `200` status
- **2026-08-28** `d0119cf38f9c`: 3 info
  - added the optional property `data/items/distinct_value_count` to the response with the `200` status
  - added the optional property `data/items/has_differing_values` to the response with the `200` status
  - added the optional property `data/items/resolved_at` to the response with the `200` status

[Operation history](https://skmtc.dev/lev/apis/lev-api/changes/api/external/v2/deals/:deal_id/index/search/post.md)

---

[API](https://skmtc.dev/lev/apis/lev-api.md) - [All operations](https://skmtc.dev/lev/apis/lev-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lev/apis/lev-api/revisions/6330d0ef0603?raw)