> ## 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 Repository

> Search the indexed documents in one repository 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 one repository by meaning and returns the best-matching passages, highest score first. A passage matches when it says what `query` asks about, even in different words. The call is synchronous: results come back in the same response.

Only documents that are `indexed` are searched. Documents still `pending` are skipped without an error. To search many repositories at once, use [Search Knowledge](/api-reference/search/search-knowledge).

With `folder_id`, the search ranks the repository's 100 best passages and keeps the ones in the folder and its subfolders. A folder search can therefore return fewer than `limit` results.

## Authentication

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

## Path parameters

**repository\_id** `string` *required*

The repository id.

## Body parameters

**query** `string` *required*

What to look for, up to 1,000 characters. A question or a phrase both work, for example `"break clause notice period"`.

**folder\_id** `string`

Only return passages from this folder and its subfolders.

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

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

## Response

Returns `200` with `{ "items": [...] }`. 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.

```bash cURL theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/repositories/b23066a1-44cb-4b31-8b44-c723dc507d9b/search" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "tenant break clause notice period",
    "limit": 2
  }'
```

```json Response theme={null}
{
  "items": [
    {
      "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 Tenant may terminate this Lease on the Break Date by giving the Landlord not less than six months' written notice.",
      "score": 0.91
    },
    {
      "file_id": "d905ed0c-2d53-4cee-9abf-2c2d75df1f7b",
      "file_name": "Lease - 2 Station Approach.docx",
      "repository_id": "b23066a1-44cb-4b31-8b44-c723dc507d9b",
      "document_id": "92a6c215-2cae-4d2f-ad06-8a1c39183706",
      "snippet": "Any break notice served under clause 9.1 must be served at least nine months before the relevant Break Date.",
      "score": 0.84
    }
  ]
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | `query` is missing, empty or longer than 1,000 characters, `limit` is outside `1`–`50`, or the body has an unknown field. |
| 400 | `repository_folder_tree_too_large` | `folder_id` is set and the repository has more than 5,000 folders. |
| 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` | No repository with this id, the caller cannot read it, or `folder_id` is not a folder in it. |
| 503 | `upstream_timeout` | The search index did not answer in time. Retry. |


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