---
title: "Search"
method: POST
path: "/api/v1/index/search"
tags: ["index"]
---

# Search

`POST /api/v1/index/search`

## Request

- Base URL: `https://api.usesynth.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.usesynth.ai/api/v1/index/search`
- Auth: none declared. Required headers: `Idempotency-Key`

## Headers

- `Idempotency-Key` string, required

## Request body

- SearchSpecInput
  - `query` string, required
  - `mode` 'fast' | 'deep'
  - `scope` SearchScope
    - `visibility` 'public' | 'private'
    - `collection_ids` string[]
  - `filters` SearchFilters
    - `kinds` ContributionKind[]
    - `research_areas` ResearchArea[]
    - `workflow_stages` WorkflowStage[]
    - `tags_any` string[]
    - `tags_all` string[]
    - `tags_none` string[]
  - `content` SearchContent
    - `max_results` integer
    - `max_excerpts_per_result` integer
    - `relative_score_floor` number: After lexical ranking, drop hits below this fraction of the top BM25 score. Omit for 0; matching hits fill max_results.
  - `limits` SearchExecutionLimits: Caller ceilings for deep execution; server policy may only tighten them. DEEP is usage-priced, so tool use is bounded by what the caller authorizes (``billing.max_charge_cents`` caps model spend) and by the deadline; these counts are safety maxima, sized so one Search's usage receipt stays within the monitor's 1024-operation bound. See search-access-funding.md.
    - `deadline_seconds` integer
    - `max_model_turns` integer
    - `max_searches` integer
    - `max_reads` integer
    - `max_active_context_tokens` integer
    - `max_inference_tokens` integer, nullable
    - `max_cost_usd_micros` integer, nullable
  - `billing` SearchBillingConstraints: Caller-owned retail spending bounds; never an execution-cost budget. See ``notes/specifications/synth-index/search-access-funding.md``. Both fields are part of the immutable Search intent. Organization consent is still required; this object can only narrow that authority.
    - `allow_wallet` boolean
    - `max_charge_cents` integer, nullable

## Response `200`

Successful Response

- SearchResult: What every Index search delivers, FAST and DEEP alike. Text whose claims cite contribution IDs inline (``[<contribution_id>]``) and the list of those contributions in first-appearance order. No ranked hits, excerpts, titles or URLs: callers fetch contributions they want by ID. The modes differ only behind the scenes. The monitor releases this shape by fixed rules (OpenMonitor ``monitor/index_cited_summary.py``).
  - `search_id` string, required
  - `request_id` string, required
  - `requested_mode` 'fast' | 'deep', required
  - `effective_mode` 'fast' | 'deep', required
  - `status` 'completed' | 'partial', required
  - `partial_reason` 'deadline_exceeded' | 'token_budget_exhausted' | 'cost_budget_exhausted' | 'tool_limit_exhausted' | 'evidence_revoked', required
  - `corpus_generation` string, required
  - `ranker_version` string, required
  - `parser_version` string, required
  - `taxonomy_version` string, required
  - `execution_versions` SearchExecutionVersions, required: Exact implementation identities used by one result. An identity the execution did not use is omitted, never ``null``.
    - `corpus_generation` string, required
    - `ranker_version` string, required
    - `parser_version` string, required
    - `taxonomy_version` string, required
    - `reranker_version` string, nullable
    - `policy_version` string, nullable
    - `agent_version` string, nullable
    - `model_version` string, nullable
  - `usage` SearchUsage, required: Server-authored successful logical search receipt; never contributor earnings.
    - `mode` 'fast' | 'deep'
    - `billing_scope` 'public' | 'private', required
    - `logical_units` integer
    - `price_version` string, nullable
    - `amount_cents` integer, required
    - `receipt_id` string, required
    - `search_calls` integer
    - `read_calls` integer
    - `input_tokens` integer
    - `output_tokens` integer
    - `inference_cost_usd_micros` integer
    - `funding_source` 'none' | 'promo_credit' | 'deep_beta' | 'wallet' | 'service_free_public'
    - `settlement_outcome` 'complete' | 'insufficient_evidence' | 'usable_partial' | 'infrastructure_stopped' | 'no_deliverable' | 'infrastructure_failure' | 'cancelled' | 'access_revoked': Server-derived retail outcome, distinct from lifecycle state.
    - `retail_amount_cents` integer, nullable
    - `allowance_units_consumed` integer
    - `allowance_value_cents` integer
    - `wallet_debit_cents` integer
  - `response` string, required
  - `citations` ContributionReference[], required
    - `contribution_id` string, required
    - `revision_id` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/usesynth/apis/synth-api.md) - [All operations](https://skmtc.dev/usesynth/apis/synth-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usesynth/apis/synth-api/revisions/4d199548e98a?raw)