Search Knowledge

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

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

POST

api

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

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

string

required

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

string[]

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

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.

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.

string[]

The repositories this search covered.

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

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

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

Body parameters

Response

Errors

​Authentication

​Body parameters

​Response

​Errors

Authentication

Body parameters

Response

Errors