---
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`

Search canonical indexed deal facts by natural-language context.

This is a read/enrichment endpoint over Metric SOT. It complements the
structured deal detail endpoints by returning ranked facts plus source
metadata such as document file name and pages.

## Path parameters

- `deal_id` integer, required

## Request body

- DealIndexSearchRequest — POST /api/external/v2/deals/<id>/index/search request body.
  - `context` string, required — Natural-language deal-data search context.
  - `min_score` number — Minimum cosine similarity threshold (0-1).
  - `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
    - `category_label` string, nullable
    - `needs_review` 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

---

[API](https://skmtc.net/lev/apis/lev-api.md) · [All operations](https://skmtc.net/lev/apis/lev-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lev/lev-api/versions/e1915e1423cf/schema)