---
title: "Search"
method: POST
path: "/v1/namespaces/{namespace}/search"
tags: ["Search"]
---

# Search

`POST /v1/namespaces/{namespace}/search`

Searches the documents in a namespace.

Set `multiturn: true` to enable multi-turn mode, which returns a `session_id` and may return `clarification_needed` status when the system needs more information.

Set `stream: true` to receive results as server-sent events; see `SearchStreamEvent` for the event shape. The stream closes after either a `session_result` or `error` event.

## Request body

- SearchRequest
  - `objective` string, required — One sentence describing what you are looking for.
  - `context` string, required — Additional context that helps the search system understand your intent. For example, relevant terminology, constraints, or prior knowledge.
  - `filters` union — Recursive filter object. One of: `{ $and: [Filter, ...] }` (all must match), `{ $or: [Filter, ...] }` (any must match), or `{ field_name: FieldCondition }` (field-level condition).
    - object
      - `$and` Filter[], required
    - object
      - `$or` Filter[], required
    - object
  - `stream` boolean — Whether to stream the response as server-sent events.
  - `include_attributes` boolean — Whether to include document attributes in search results.
  - `multiturn` boolean — Enable multi-turn mode. When `true`, the response includes a `session_id` and may return `clarification_needed` status. When `false` (default), the search always completes in a single request.

## Response `200`

Successful response. When `stream` is `false` (default), returns JSON. When `stream` is `true`, returns `text/event-stream`.

- SearchResponse
  - `session_id` string, required — Unique identifier for this search session.
  - `status` 'completed' | 'clarification_needed' | 'failed', required
  - `documents_scanned` integer — Number of documents scanned during the search.
  - `queries_executed` integer — Number of queries executed during the search.
  - `synthesis` string, required — Synthesized summary of all findings.
  - `results` SearchResult[], required
    - `finding` string, required
    - `id` string, required — Source document ID.
    - `excerpts` string[], required
    - `attributes` object — Document attributes. Present when `include_attributes` is `true`.
  - `clarification_needed` object — Present when status is `clarification_needed`.
    - `question` string — The clarification question.
    - `options` string[] — Suggested answer options.

## Other responses

- `400` — The request was invalid.
- `401` — Missing or invalid API key.
- `404` — The requested resource was not found.

---

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