curl --request POST \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/tools/read-file \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"path": "<string>"
}
'{
"components_omitted": [
"<string>"
],
"components_returned": [
"<string>"
],
"content": "<string>",
"file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"pages_returned": [
123
],
"path": "<string>",
"truncated": true,
"job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"line_count": 123,
"line_end": 123,
"line_start": 123,
"sql_tables": [
"<string>"
],
"table": {
"first_line": 123,
"header": "<string>",
"last_line": 123,
"title": "<string>",
"rows": 123
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}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.
curl --request POST \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/tools/read-file \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"path": "<string>"
}
'{
"components_omitted": [
"<string>"
],
"components_returned": [
"<string>"
],
"content": "<string>",
"file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"pages_returned": [
123
],
"path": "<string>",
"truncated": true,
"job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"line_count": 123,
"line_end": 123,
"line_start": 123,
"sql_tables": [
"<string>"
],
"table": {
"first_line": 123,
"header": "<string>",
"last_line": 123,
"title": "<string>",
"rows": 123
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}Authorizations
Headers
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.
200Path Parameters
Workspace identifier.
Body
Request body for read-file.
path names an uploaded source file — the only namespace this tool
serves. A workspace-internal derivative path is refused with
invalid_request naming the uploaded file that owns it.
component scopes the read to one public component by name — a
spreadsheet tab or a pdf section, as listed by file-metadata.
pages is 1-based and selects on the file's absolute page numbers;
out-of-range pages are ignored (absent from pages_returned). Selected
pages come back de-duplicated in document order, whatever order they were
asked in. Spreadsheets have no pages — scope those with component
instead.
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.
1 - 1024One tab or section to read, named as file-metadata lists it; omitted: the whole file.
Last line to return, inclusive and 1-based like line_start. Omitted: the last line.
x >= 1First 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.
x >= 1Character budget for the returned text; past it truncated is true.
1 <= x <= 10000001-based page numbers to read; omitted: every page. Spreadsheets have no pages.
Response
Successful Response
Response body for read-file.
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
prefixed by a one-line header naming the component. components_returned
lists what contributed to content; components_omitted lists
components that were cut for size — the character budget ran out, or a
part was too large to serve — or that have no text rendering at all (a
query-only tab; ask it with qa-file) — so an absent component is
always visible, never a silently missing tab. Unnamed components (a
recording, a raw upload) are listed by kind. A table a PDF page holds
comes as rows — one | a | b | line each under a header that joins the
stacked column headings — the way grep and hybrid-search print it.
The external operation job; absent for commands inside a search job.
How many lines the whole selected text has, when the request named a line range; None otherwise.
Last line returned (inclusive) when the request named a line range; None otherwise or when line_start is past the end of the text.
First line returned (1-based) when the request named a line range; None otherwise.
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.
When a line range starts inside a table, below its header row: that table's lines, title and header, so the rows read with their column names.
Show child attributes
Show child attributes