Create Repository

Create an empty repository to hold and search documents.

POST /api/v1/repositories

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/repositories" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Commercial leases",
    "description": "Signed leases for the UK retail estate."
  }'

Response

{
  "id": "b23066a1-44cb-4b31-8b44-c723dc507d9b",
  "name": "Commercial leases",
  "description": "Signed leases for the UK retail estate.",
  "document_count": 0,
  "url": "https://app.wordsmith.ai/repositories/b23066a1-44cb-4b31-8b44-c723dc507d9b",
  "created_at": "2026-10-13T08:12:04Z",
  "updated_at": "2026-10-13T08:12:04Z",
  "indexing_status": "idle"
}

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

Creates an empty repository. A repository indexes its documents so you can search them. Add files to it with Add Documents.

The caller becomes the repository’s admin, as if they had created it in the app. Share it in the app to give others access.

Authentication

Requires an API key, or an OAuth token with repositories:write. The caller’s role must allow creating repositories.

Body parameters

name · string · required

The repository name, up to 200 characters. Names do not have to be unique.

description · string

What the repository holds, up to 2,000 characters. Shown in the app and returned by the API.

Response

Returns 201 with the new repository. document_count is 0 and indexing_status is idle.

indexing_status · string

idle once every document is indexed, indexing while any document is still waiting, failed when any document could not be indexed.

The other fields are the ones List Repositories returns.

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/repositories" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Commercial leases",
    "description": "Signed leases for the UK retail estate."
  }'

Response

{
  "id": "b23066a1-44cb-4b31-8b44-c723dc507d9b",
  "name": "Commercial leases",
  "description": "Signed leases for the UK retail estate.",
  "document_count": 0,
  "url": "https://app.wordsmith.ai/repositories/b23066a1-44cb-4b31-8b44-c723dc507d9b",
  "created_at": "2026-10-13T08:12:04Z",
  "updated_at": "2026-10-13T08:12:04Z",
  "indexing_status": "idle"
}

Errors

Status	error_code	When
400	invalid_request_body	name is missing, empty or longer than 200 characters, description is longer than 2,000, 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.
403	forbidden	The caller’s role does not allow creating repositories.