Get task file text

Read the extracted plain text of one of a task’s files, one page at a time.

GET /api/v1/tasks/{task_id}/files/{file_id}/text

cURL

curl "https://api.wordsmith.ai/api/v1/tasks/9f8e7d6c-5b4a-3210-9876-543210fedcba/files/7c9e6679-7425-40de-944b-e07fc1f90ae7/text?offset=0&max_chars=20000" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

First page

{
  "file_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "text": "MUTUAL NON-DISCLOSURE AGREEMENT\n\nThis Agreement is made on 1 October 2026 between ...",
  "offset": 0,
  "next_offset": 20000,
  "total_chars": 46218
}

Returns one page of the plain text of a file on the task. It works like Get file text, but needs only the tasks:read scope, and only for files the task lists. 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.

​

Authentication

Send an API key, or an OAuth access token with the tasks:read scope, as a bearer token in the Authorization header.

​

Path parameters

task_id · string · required

The task the file is on. Accepts a display id like #12 or the task’s UUID.

file_id · string (uuid) · required

An id from the task’s input_files or output_files, or from a comment’s or thread message’s file_ids. Attaching stores a copy with a new id, so the id you attached is not on the task.

​

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.

cURL

curl "https://api.wordsmith.ai/api/v1/tasks/9f8e7d6c-5b4a-3210-9876-543210fedcba/files/7c9e6679-7425-40de-944b-e07fc1f90ae7/text?offset=0&max_chars=20000" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

First page

{
  "file_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "text": "MUTUAL NON-DISCLOSURE AGREEMENT\n\nThis Agreement is made on 1 October 2026 between ...",
  "offset": 0,
  "next_offset": 20000,
  "total_chars": 46218
}

​

Errors

See 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.
404	resource_not_found	The task does not exist or you cannot read it, the task does not list the file, or the file’s 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.