# Index Overview

> Understand the Lev deal index — canonical facts, the documents behind them, and the endpoints for reading, correcting, and recording deal data.

Source: https://www.lev.com/docs/build/index/overview

Last updated: 2026-09-16

---
## What the Deal Index Is

The index stores three kinds of thing, and most confusion comes from mixing them up.

- **Fact** — the canonical value for one metric on one entity, the NOI Lev will show you for this property. Identified by a `sot_id`.
- **Observation** — one value an extractor pulled from one document, with its file, page range, and confidence. A fact can have several, and one of them is promoted to canonical.
- **Metric definition** — an entry in the catalog of what is recordable at all, carrying the `metric_id` and `value_type` you need to write a value.

Facts attach to **entities**, not just to the deal. A deal has an entity for itself, one per property, and others for the sponsor, broker, and team members. A property metric such as in-place NOI belongs to a `property:` entity, not the `deal:` entity.

## Endpoints

| Endpoint | Description |
|----------|-------------|
| [`POST /deals/{id}/index/search`](/build/index/search) | Find canonical facts and their source documents |
| [`POST /deals/{id}/index/observations`](/build/index/observations) | List the per-document values behind a fact |
| [`PATCH /deals/{id}/index/facts`](/build/index/update-fact) | Change one canonical value |
| [`GET /deals/{id}/index/metric-definitions`](/build/index/metric-definitions) | List what can be recorded |
| [`GET /deals/{id}/index/entities`](/build/index/entities) | List what a fact can attach to |
| [`POST /deals/{id}/index/facts`](/build/index/insert-facts) | Record new values |

## Read a Fact and Trace It

To answer "what is the NOI, and where did it come from":

1. **Search for the fact.** Call [Search Index](/build/index/search) with a context describing what you want. Each result carries the canonical value, a `sot_id`, and a `source` block naming the document.
2. **Pull its observations.** Pass that `sot_id` to [Index Observations](/build/index/observations) to see every value extracted for that fact, one per document, with page ranges and confidence.
3. **Request links only when you need them.** Set `include_signed_urls=true` on either call to get short-lived download URLs for the source documents.

## Record or Correct a Fact

Correcting a value the deal already has is a different path from recording one it has never had.

**To correct an existing fact**, search for it, then call [Update Index Fact](/build/index/update-fact) with its `sot_id`. Pass an `observation_id` to promote a value an extractor already found, which keeps the source document and page range attached. Pass a raw value only when no observation is right.

**To record a new fact**, look up the metric with [Metric Definitions](/build/index/metric-definitions), look up the target with [Index Entities](/build/index/entities), then post the pair to [Insert Index Facts](/build/index/insert-facts). Send an explicit `entity_ref` that matches the metric's entity type.

## What Search Does Not Do

[Search Index](/build/index/search) takes a natural-language `context` and returns ranked matches above a similarity threshold. It is not an export. A single call returns at most 200 facts and takes no offset, so there is no way to page through a deal's full index.

  Ask for what you need by name rather than assuming a broad query returned everything the deal holds. If you need a specific metric, search for that metric.