Search Repository

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
  }'

{
  "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
    }
  ]
}

POST

api

repositories

{repository_id}

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
  }'

{
  "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
    }
  ]
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

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. 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

string

required

The repository id.

Body parameters

string

required

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

string

Only return passages from this folder and its subfolders.

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.

object[]

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

Show properties

string | null

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

string

The document, as Get Document takes it.

string

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

number

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

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
  }'

{
  "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.

Preview

Agents, playbooks and blueprints

Sessions

Playbook authoring

Drafts

Files

Document actions

Operations

Research

Reports

Reviews

Organisation

Sharing

Usage and value

Repositories and search

Authentication

Path parameters

Body parameters

Response

Errors

​Authentication

​Path parameters

​Body parameters

​Response

​Errors

Authentication

Path parameters

Body parameters

Response

Errors