---
title: "Search Contracts"
method: POST
path: "/api/internal/contracts/search"
tags: ["Contracts"]
---

# Search Contracts

`POST /api/internal/contracts/search`

Search contracts (retool.contract_data).

Three orthogonal text inputs, AND'd together:

- ``vendors``: array of vendor terms (weight A in text_search_strict)
- ``products``: array of product terms (weight B in text_search_strict)
- ``query``: free-text over raw_text (text_search_prose, english config)

See ContractSearchFilters docstring for the full syntax. All filters are
optional — the table is small enough (~7K rows) to allow unbounded scans.

## Request body

- ContractSearchFilters — Search filters for contracts (retool.contract_data). The vendor + product columns have been removed from contract_data — they now live in sibling tables (``retool.vendors``, ``retool.vendor_products``). The endpoint currently searches **only** the prose column (``text_search_prose``) over ``raw_text``. Query syntax (websearch_to_tsquery, english config — stemming on): bare words: "granicus laserfiche" implicit AND quoted phrase: '"early termination"' exact phrase OR: "granicus OR tyler" literal OR keyword exclude: "granicus -laserfiche" prefix - to exclude All filters are optional. ~7K rows is small enough to permit unbounded scans, but supplying at least a query or institution scope is recommended. Vendor / product search will be re-added when the new ``retool.vendors`` and ``retool.vendor_products`` tables are integrated into the endpoint.
  - `query` string, nullable — Free-text search over the contract body (raw_text, english config, stemming on). Supports websearch syntax: quoted phrases, OR, leading '-' to exclude.
  - `contract_start_after` string, date, nullable
  - `contract_start_before` string, date, nullable
  - `contract_end_after` string, date, nullable
  - `contract_end_before` string, date, nullable
  - `min_total_acv` number, nullable
  - `max_total_acv` number, nullable
  - `min_annual_acv` number, nullable
  - `max_annual_acv` number, nullable
  - `institution_ids` string[], nullable
  - `states` string[], nullable
  - `source_tables` string[], nullable
  - `sort` 'relevance' | 'contract_start_date_desc' | 'contract_start_date_asc' | 'contract_end_date_asc' | 'contract_end_date_desc' | 'total_acv_desc' | 'annual_acv_desc' | 'created_at_desc'
  - `offset` integer
  - `limit` integer

## Response `200`

Successful Response

- PaginatedResponseContractResponse
  - `results` ContractResponse[], required
    - `id` string, required
    - `institution_id` string, required
    - `institution_name` string, nullable
    - `institution_state` string, nullable
    - `institution_type` string, nullable
    - `annual_acv` number, nullable
    - `total_acv` number, nullable
    - `contract_start_date` string, date, nullable
    - `contract_end_date` string, date, nullable
    - `signees` unknown
    - `file_path` string, required
    - `created_at` string, date-time, nullable
    - `relevance` number, nullable
  - `total` integer, required
  - `offset` integer, required
  - `limit` integer, required

## Other responses

- `422` — Validation Error

---

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