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

# Add Documents

> Add uploaded files to a repository and start indexing them.

> [!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).

Adds up to 100 files to a repository as documents and starts indexing them. The call returns a `repository_indexing` [operation](/api-reference/operations/get-operation) straight away. Indexing takes seconds per document.

The documents appear in [List Documents](/api-reference/repositories/list-documents) at once, with `indexing_status: "pending"`. Each one becomes searchable as soon as it is `indexed`, before the whole batch finishes.

What happens to each file:

* A file you uploaded, still in your own space, moves into the repository, as an upload in the app does. Anyone who can read the repository can then read it, and [removing the document](/api-reference/repositories/remove-document) or deleting the repository deletes the file.
* A file that already belongs to something else, such as another repository's document or a conversation, is copied into the repository instead. The document's `file_id` is then the copy's, and removing the document deletes only the copy.
* A file that is already a document of this repository, itself or as a copy, is not added again. It still counts in the operation's result.
* A different file with the same name as a document already in the repository replaces that document. Of several files with the same name in one request, only the last is added.
* An archive (`.zip`, `.tar`, `.7z`, mailbox files) is refused. Add the files inside it instead.

Get a `file_id` from [Complete Upload](/api-reference/files/complete-upload), [Import File](/api-reference/files/import-file) or [Create File](/api-reference/files/create-file).

## Authentication

Requires an API key, or an OAuth token with `repositories:write` and `files:read`. The caller needs edit access to the repository and read access to every file.

## Path parameters

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

The repository id.

## Headers

**Idempotency-Key** `string`

A unique string for this request, such as a UUID, up to 255 characters. A repeat with the same key within 30 days returns the same operation with `200` instead of adding the files again.

## Body parameters

**file\_ids** `string[]` *required*

The files to add, from `1` to `100` file ids. A repeated id is added once.

**folder\_id** `string`

The folder to put the documents in. Leave it out to add them at the top level. Create folders with [Create Folder](/api-reference/repositories/create-folder).

**wait** `integer` (default: 0)

Seconds to wait for indexing to finish before responding, from `0` to `20`. If it finishes in time, the response carries the finished operation.

**callback\_url** `string`

An HTTPS URL that receives a signed POST with the operation when it finishes. API keys only: an OAuth caller waits on the operation instead.

## Response

Returns `202` with the operation, or `200` with the earlier operation for a repeated `Idempotency-Key`. Its `type` is `repository_indexing` and its `resource` is the repository. While it runs, `progress.completed` and `progress.total` count documents.

When it succeeds, `result` holds `{ "indexed", "failed" }`: how many of the documents were indexed and how many could not be. A document that fails does not fail the operation; find it with [List Documents](/api-reference/repositories/list-documents). The operation cannot be cancelled.

```bash cURL theme={null}
curl -X POST "https://api.wordsmith.ai/api/v1/repositories/b23066a1-44cb-4b31-8b44-c723dc507d9b/documents" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1f6a3c2e-8d40-4b7e-a9c5-3e2d7b8f0a14" \
  -d '{
    "file_ids": [
      "5fd5db90-5cd3-46b6-87d9-c828732551ef",
      "ee4c67ec-2355-4096-b147-f89ddef2029d",
      "d905ed0c-2d53-4cee-9abf-2c2d75df1f7b"
    ],
    "folder_id": "d85cb28c-9081-4b90-90be-be843b16c493"
  }'
```

```json Running theme={null}
{
  "id": "05d989f4-4b06-4507-9616-8c147f862c83",
  "type": "repository_indexing",
  "status": "running",
  "progress": { "stage": "indexing", "completed": 0, "total": 3 },
  "resource": { "type": "repository", "id": "b23066a1-44cb-4b31-8b44-c723dc507d9b" },
  "result": null,
  "error": null,
  "poll_after_seconds": 5,
  "created_at": "2026-10-13T09:14:22Z",
  "updated_at": "2026-10-13T09:14:22Z",
  "completed_at": null
}
```

```json Succeeded theme={null}
{
  "id": "05d989f4-4b06-4507-9616-8c147f862c83",
  "type": "repository_indexing",
  "status": "succeeded",
  "progress": null,
  "resource": { "type": "repository", "id": "b23066a1-44cb-4b31-8b44-c723dc507d9b" },
  "result": { "indexed": 2, "failed": 1 },
  "error": null,
  "poll_after_seconds": null,
  "created_at": "2026-10-13T09:14:22Z",
  "updated_at": "2026-10-13T09:16:05Z",
  "completed_at": "2026-10-13T09:16:05Z"
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_request_body` | `file_ids` is empty or has more than 100 ids, or the body has an unknown field. |
| 400 | `invalid_wait` | `wait` is outside `0`–`20`. |
| 400 | `invalid_callback_url` | `callback_url` is not a public https URL. |
| 400 | `callback_signing_unavailable` | The API key has no webhook secret to sign the callback with. Create a new API key, or long-poll the operation instead. |
| 400 | `invalid_idempotency_key` | `Idempotency-Key` is empty or longer than 255 characters. |
| 400 | `bad_request` | A file is an archive, `folder_id` is a folder synced from a connected source, or `callback_url` was sent with an OAuth token. |
| 400 | `repository_document_limit_exceeded` | Your organisation has reached its document limit. |
| 401 | `unauthorized` | The API key or token is missing or invalid. |
| 403 | `mcp_not_enabled` | Your organisation is not in the preview. |
| 403 | `insufficient_scope` | The OAuth token lacks `files:read`. |
| 403 | `forbidden` | The caller can read the repository but cannot edit it. |
| 404 | `resource_not_found` | No repository with this id, the caller cannot read it, a file the caller cannot read, or `folder_id` is not a folder in it. |
| 409 | `idempotency_key_reused` | The `Idempotency-Key` was used within 30 days with a different body. |


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