Search Knowledge

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

POST /api/v1/search

cURL

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

Response

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

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

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.

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.

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

cURL

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

Response

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