> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyformat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Rank a workflow's knowledge corpus by relevance to a query

*Rate limit tier: **general**, 600 requests/min. See [Rate limits](/api-reference-v3/introduction#rate-limits).*

Ranks a workflow's knowledge corpus by relevance (BM25) to `query` — for a topic-style question such as "where is termination discussed", not an exact string, a count, or a sum. For an answer with citations, use [Ask](/api-reference-v3/knowledge/ask); for the full tree, use [List](/api-reference-v3/knowledge/list).

Each hit carries a relevance `rank` (higher first) and a `snippet`: a window of text around the best-matching term, wrapped in `«»`. Ranking is relevance, not match count — a document matching the query term fewer times can still outrank one matching it more, and a document matching no query term as a whole word is not returned.

## Requires a knowledge base

Same requirement as `ask`: the workflow needs a **knowledge node**, or this returns `409 KNOWLEDGE_NOT_ENABLED`. `409 KNOWLEDGE_NOT_READY` means no usable snapshot has ever been published. Unlike `ask`, search is never billed, so `402` cannot occur here.

## Folder

`folder` narrows ranking to one top-level source folder — the first path segment (e.g. `contracts`), not a nested path. Omitting it merges every folder's statistics into one corpus-wide ranking. An unrecognized folder name is a `404`.

## Query length

`query` is 1 to 512 characters.

## Limit

`limit` caps the number of hits, 1 to 50, default 10.

## Errors

| Status | `error_code`            | Meaning                                                                                              |
| ------ | ----------------------- | ---------------------------------------------------------------------------------------------------- |
| `400`  | `VALIDATION_ERROR`      | `query` was empty or over 512 characters, or `limit` was outside 1 to 50.                            |
| `404`  | `NOT_FOUND`             | Unknown workflow, one belonging to another organization, or `folder` names no folder in this corpus. |
| `409`  | `KNOWLEDGE_NOT_ENABLED` | The workflow has no Knowledge node. Do not retry: add the node first.                                |
| `409`  | `KNOWLEDGE_NOT_READY`   | No knowledge snapshot has ever been published for this workflow. Wait if indexing is in progress.    |
| `504`  | `GATEWAY_TIMEOUT`       | The search exceeded the agent's own time ceiling. Retry.                                             |

<RequestExample>
  ```bash curl theme={null}
  curl -X GET 'https://api.anyformat.ai/v3/workflows/0686bb97-8c30-70f0-8000-97669e000eb8/knowledge/search?query=termination+notice&limit=5' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```python Python (requests) theme={null}
  import requests

  workflow_id = "0686bb97-8c30-70f0-8000-97669e000eb8"
  url = f"https://api.anyformat.ai/v3/workflows/{workflow_id}/knowledge/search"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}

  hits = requests.get(url, headers=headers, params={"query": "termination notice", "limit": 5}).json()
  for hit in hits:
      print(hit["path"], hit["rank"], hit["snippet"])
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200 OK) theme={null}
  [
    {
      "path": "2026-07/meridian-msa.md",
      "folder": "2026-07",
      "title": "Meridian MSA",
      "page_count": 3,
      "snippet": "Either Party may terminate upon ninety (90) «days'» notice.",
      "rank": 4.2
    }
  ]
  ```

  ```json Response (409, no knowledge base) theme={null}
  {
    "error": "Knowledge base not enabled",
    "detail": "This workflow has no knowledge base. Add a knowledge node. New completed runs then ingest documents; index earlier processed documents from the app's Knowledge tab.",
    "error_code": "KNOWLEDGE_NOT_ENABLED",
    "retryable": false
  }
  ```
</ResponseExample>