---
title: "Create"
method: POST
path: "/api/v1/index/searches"
tags: ["index"]
---

# Create

`POST /api/v1/index/searches`

## 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/searches`
- 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

- Search: Authorized lifecycle snapshot; a client wait timeout does not mutate it.
  - `search_id` string, required
  - `spec` SearchSpecOutput, required
    - `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
  - `state` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', required
  - `requested_mode` 'fast' | 'deep', required
  - `effective_mode` 'fast' | 'deep'
  - `cancellation_requested` boolean
  - `result_available` boolean
  - `failure` PackagesContributionsSearchSearchFailure
    - `code` string, required
    - `retryable` boolean, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, 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)