NAnace
tools

read_file

Read the text of one uploaded file.

Cost class: fast.

path names an uploaded source file — the only namespace this tool serves. A workspace-internal path is refused with invalid_request naming the uploaded file to use instead.

A file with several components (a spreadsheet's tabs, a pdf's sections) answers with their text concatenated in the file's own order, each part under a one-line header naming the component; components_returned and components_omitted report exactly what made it into the budget. Scope the read with component=<name> (the names file_metadata lists) when only one tab or section matters, and with pages (1-based) for paged documents — spreadsheets have no pages, so scope those by component instead. Images are refused — ask about them with qa_file.

Args: body: Source path, optional component name, optional page list, and character limit. workspace: Resolved workspace and caller access predicate. A non-existent workspace returns workspace_not_found before the body executes. session: Database session.

post/v1/workspaces/{workspace_id}/tools/read-file

Request

Path parameters

workspace_idstring uuid required

Workspace identifier.

Headers

Idempotency-Keystring nullable

Replaying a request with the same key returns the original job with 200, never a second job. The key is kept with the job for replay and never cleared, so it must not contain personal data.

Request body

pathstring required

The uploaded file's full path relative to the workspace root, exactly as it was uploaded and as listings and search results print it — e.g. evidence/doc-7f83/contract.pdf. Not a bare file name (a file's file_name), a folder, a file id, or a path that starts with the workspace id.

pagesinteger[] nullable

1-based page numbers to read; omitted: every page. Spreadsheets have no pages.

componentstring nullable

One tab or section to read, named as file-metadata lists it; omitted: the whole file.

max_charsinteger

Character budget for the returned text; past it truncated is true.

line_startinteger nullable

First line to return, 1-based, counted in the text this read would return without a line range (after component and page selection). Omitted: line 1.

line_endinteger nullable

Last line to return, inclusive and 1-based like line_start. Omitted: the last line.

Response

Successful Response

pathstring required
file_idstring uuid required
contentstring required
pages_returnedinteger[] required
truncatedboolean required
components_returnedstring[] required
components_omittedstring[] required
sql_tablesstring[]

The run-sql names of the tables holding the rows of the long tables printed in the returned sections — count, total or rank those rows there rather than from the text.

line_startinteger nullable

First line returned (1-based) when the request named a line range; None otherwise.

line_endinteger nullable

Last line returned (inclusive) when the request named a line range; None otherwise or when line_start is past the end of the text.

line_countinteger nullable

How many lines the whole selected text has, when the request named a line range; None otherwise.

job_idstring uuid nullable

The external operation job; absent for commands inside a search job.

Changes

No recorded changes to this operation across all 1 revision of this API.