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

# Get File Text

> Read a file's extracted plain text, one page at a time.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP and files pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Returns one page of a file's plain text. Wordsmith extracts the text from documents, spreadsheets, presentations, images and other supported types. Tracked changes in a Word document are kept.

Read a long file page by page:

1. Call without `offset`. The first page starts at character 0.
2. While `next_offset` is not `null`, call again with `offset` set to `next_offset`.
3. When `next_offset` is `null`, you have the last page.

`total_chars` is the length of the whole text, so you can tell how many pages are left. An `offset` at or past the end returns empty `text` and a `null` `next_offset`.

A file is served only once its malware scan is clean. While the scan is still running, the response is `409 scan_in_progress`; retry shortly. A file the scan flagged returns `404`, as a missing file does.

## Authentication

Send an API key, or an OAuth access token with the `files:read` scope, as a bearer token in the `Authorization` header. `files:write` does not include `files:read`. A token without the scope gets `403` with `"error": "insufficient_scope"`.

## Path parameters

**file\_id** `string (uuid)` *required*

The file's id.

## Query parameters

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

Character offset to start the page at. 0 or greater.

**max\_chars** `integer` (default: 20000)

The most characters to return. 1 or greater. Values over 100,000 are treated as 100,000.

## Response

**file\_id** `string (uuid)`

The file's id.

**text** `string`

This page of the text.

**offset** `integer`

Character offset of the first character in `text`.

**next\_offset** `integer | null`

The offset to read the next page from. `null` on the last page.

**total\_chars** `integer`

The number of characters in the whole text.

```bash cURL theme={null}
curl "https://api.wordsmith.ai/api/v1/files/7c3e9a51-2d84-4f06-b1c7-5e9d0a2f8b63/text?offset=0&max_chars=20000" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

```json First page theme={null}
{
  "file_id": "7c3e9a51-2d84-4f06-b1c7-5e9d0a2f8b63",
  "text": "MUTUAL NON-DISCLOSURE AGREEMENT\n\nThis Agreement is made on 1 October 2026 between ...",
  "offset": 0,
  "next_offset": 20000,
  "total_chars": 46218
}
```

```json Last page theme={null}
{
  "file_id": "7c3e9a51-2d84-4f06-b1c7-5e9d0a2f8b63",
  "text": "... IN WITNESS WHEREOF the parties have signed this Agreement on the date above.",
  "offset": 40000,
  "next_offset": null,
  "total_chars": 46218
}
```

## Errors

See [Errors](/errors) for the error format.

| HTTP Status | Error Code | When |
| - | - | - |
| 400 | `bad_request` | `offset` is not an integer 0 or greater, or `max_chars` is not an integer 1 or greater. |
| 400 | `unsupported_file_type` | Wordsmith cannot extract text from this file: its type is not supported, it is password-protected, empty or corrupt, or it is over 1 GB. |
| 401 | `unauthorized` | The API key is missing or invalid. |
| 403 | `mcp_not_enabled` | Your organisation is not in the preview. |
| 404 | `resource_not_found` | The file does not exist, you cannot read it, or its malware scan flagged it. |
| 409 | `scan_in_progress` | The file's malware scan has not finished. Retry shortly. |
| 503 | `temporarily_unavailable` | The document converter is busy or unavailable. Retry shortly. |


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