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

# Search Knowledge

> Search many repositories you can read in one call and get ranked passages back.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Searches several repositories by meaning and returns the best-matching passages across them, highest score first. The call is synchronous: results come back in the same response.

There is no single index across repositories. This endpoint searches each repository's index, up to five at a time, and merges the passages by score. One call searches at most **20 repositories**:

* With `repository_ids`, it searches those, up to 20.
* Without it, it searches the 20 repositories you can read that were used most recently.

`searched_repository_ids` lists the repositories the search covered. A repository whose index does not answer in time is left out of it rather than failing the search. To search one repository, or one folder in it, use [Search Repository](/api-reference/repositories/search-repository).

## Authentication

Requires an API key, or an OAuth token with `repositories:read`.

## Body parameters

**query** `string` *required*

What to look for, up to 1,000 characters. A question or a phrase both work, for example `"limitation of liability cap"`.

**repository\_ids** `string[]`

Only search these repositories, from `1` to `20`. Leave it out to search the 20 most recently used repositories the caller can read.

**limit** `integer` (default: 10)

The most results to return, from `1` to `50`.

## Response

Returns `200` with the passages and the repositories searched. There is no `cursor`: raise `limit` for more results.

**items** `object[]`

Best match first. Each item is one passage, so one document can appear more than once.

**properties**

**file\_id** `string | null`

The file behind the document. `null` for a document synced from a connected source, or an older document with no stored file.

**file\_name** `string`

**repository\_id** `string`

**document\_id** `string`

The document, as [Get Document](/api-reference/repositories/get-document) takes it.

**snippet** `string`

The matching passage, up to about 2,500 characters.

**score** `number`

How close the passage is to the query, from `0` to `1`. Compare scores within one response.

**searched\_repository\_ids** `string[]`

The repositories this search covered.

```bash cURL theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/search" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "limitation of liability cap",
    "limit": 2
  }'
```

```json Response theme={null}
{
  "items": [
    {
      "file_id": "727b3d33-8cdd-4726-9fe9-2ee2d76a76d3",
      "file_name": "Precedent - SaaS terms (customer-friendly).docx",
      "repository_id": "dc8cea44-62d7-414a-be83-1d80e9b5cc7a",
      "document_id": "20053856-fc5c-4fe0-9c0d-b7642f58e951",
      "snippet": "Neither party limits its liability for death or personal injury caused by negligence, or for fraud.",
      "score": 0.86
    },
    {
      "file_id": "5fd5db90-5cd3-46b6-87d9-c828732551ef",
      "file_name": "Lease - Unit 4 Riverside Park.pdf",
      "repository_id": "b23066a1-44cb-4b31-8b44-c723dc507d9b",
      "document_id": "612bf514-5c3e-468b-9782-d5d5a635b72d",
      "snippet": "The Landlord's liability under clause 11 is limited to the amount recovered under the Insurance Policies.",
      "score": 0.71
    }
  ],
  "searched_repository_ids": [
    "dc8cea44-62d7-414a-be83-1d80e9b5cc7a",
    "b23066a1-44cb-4b31-8b44-c723dc507d9b"
  ]
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | `query` is missing, empty or longer than 1,000 characters, `repository_ids` is empty or has more than 20 ids, `limit` is outside `1`–`50`, or the body has an unknown field. |
| 401 | `unauthorized` | The API key or token is missing or invalid. |
| 403 | `mcp_not_enabled` | Your organisation is not in the preview. |
| 404 | `resource_not_found` | A repository in `repository_ids` does not exist, or the caller cannot read it. |
| 503 | `upstream_timeout` | No repository's index answered in time. Retry. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.