NAnace
tools

read_file

Changed on

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.

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

Request

Path parameters

workspace_idstring uuid required

Workspace identifier.

Headers

Idempotency-Keystring nullable

Use the same key to recover an earlier request. A replay returned as a Job carries Idempotent-Replayed: true and replayed: true without a new charge; Job credits keeps the original cost. Re-serving a settled inline tool answer reports zero credits for that call and also carries Idempotent-Replayed: true; a fresh re-execution after a transient failure carries no header. The key is kept with the job for replay and never cleared, so it must not contain personal data.

Request body

componentstring nullable

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

line_endinteger nullable

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

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.

max_charsinteger

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

pagesinteger[] nullable

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

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.

Response

Successful Response

components_omittedstring[] required
components_returnedstring[] required
contentstring required
creditsinteger nullable

Credits billed for this call; zero for a free answer or replay, null when a billing receipt is unavailable.

file_idstring uuid required
job_idstring uuid nullable

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

line_countinteger nullable

How many lines the whole selected text has, 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_startinteger nullable

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

pages_returnedinteger[] required
pathstring required
sql_tablesstring[]

The run-sql names of the tables holding the rows of the long tables printed in the returned PDF sections — count, total or rank those rows there rather than from the text. Empty for a spreadsheet or CSV tab: its table name is file-metadata's table_name.

truncatedboolean required
waiver'repeat_of_job' | 'no_job' nullable

Why this call is free: repeat_of_job reuses an earlier answer; no_job answers without creating a job.

Changes

  • d002a3589a67Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status