Navigate tools

Search answers a question for you. The navigate tools let your own agent find the answer itself, with the tools the document service's search agent works with:

• Locate names the pages and tables most likely to hold a piece of information. A decision model walks the workspace's files, sections and pages, built at ingestion, and answers with each piece, the read that opens it and its opening text, then the tables to query. It also runs a workspace search on the need, so an exact name, number or phrase leads it to the file that holds it.
• Read-file returns a file's text: all of it, one tab or section, some pages, or a span of lines.
• Run-sql runs one read-only SELECT (DuckDB dialect) over the workspace's tables.

Each answers inline, with nothing to wait for, and reads only files that are Ready. They are free. Locates are limited to 150 per account every 10 minutes, and file reads and SQL queries together to 600. For a code agent such as Claude Code, Codex, Cursor or Pi, install the agent skill: it teaches the agent the loop below with the nace CLI.

Search or navigate toolsCopy Anchor Link

Both read the same ingested files, so a workspace set up for one works with the other.

The loopCopy Anchor Link

1. Locate the question: send what it needs as need, and the whole question as question.
2. Read the pages it names with read-file, exactly as it names them: by pages for a paged document, by line_start and line_end (and component) for a text file or a tab.
3. Query a table it names with run-sql, under its sql_table name. When the answer needs every file of a kind (a count, a list or a total over each invoice, statement or contract), locate that kind once with every: true: population lists the members, and you read each.
4. Locate again for a part still missing, naming the gap in a few words. Locate keeps no memory between calls: send back the pieces earlier calls offered as exclude and what you read as already_read, and it shows something new. The nace CLI keeps that memory for you.
5. Stop when every figure comes from a page you read or a query you ran.

LocateCopy Anchor Link

curl "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/tools/locate" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "need": "total liabilities at year end 2024",
    "question": "How did total liabilities change from 2023 to 2024?",
    "exclude": [{"path": "reports/2024/annual-report.pdf", "number": 41}]
  }'

text is the answer as the search agent reads it, and pages, tables and population hold the same as fields. It gives the best pages in full and the rest by their opening lines; send "pointer": true to name every page by its opening lines only, as a task's later locates should, so page text does not pile up in an agent's context. Its reads are written as ndi read-file ..., the document service's own CLI; nace locate prints them as nace read-file ..., with the same arguments. The first locate after the workspace's files change reads them first and can take a minute or more. A workspace whose files are kept in your own storage can't be located (422). See Locate information.

Read a fileCopy Anchor Link

curl "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/tools/read-file" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "reports/2024/annual-report.pdf", "pages": [41, 42]}'

A file with several tabs or sections answers with each under a header line naming it. truncated says max_chars (200,000 by default) cut the text, and sql_tables names the tables holding the rows of the long tables printed. A file that isn't ingested yet answers 409 file_not_ingested. See Read a file.

Run a SQL queryCopy Anchor Link

curl "https://console.nace.ai/v1/workspaces/$WORKSPACE_ID/tools/run-sql" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT account, amount FROM tb_2024_trial_balance WHERE amount > 10000"}'

The answer holds the first rows. Every result is kept:

• result.handle (res_…) is a table the next query in the same workspace may join, total or page with LIMIT and OFFSET. It resolves for any caller that sees the same tables of that workspace, such as another key of your account or a member you invited, and never in another workspace or account.
• result_citation.result_file is the whole result as a Parquet file: download it from download_url without the API key until download_url_expires_at. It is not one of the workspace's files.

Table names come from locate's tables, read-file's sql_tables, and the refusal of a query that names an unknown table, which lists them all. See Run a SQL query.

Timeouts and retriesCopy Anchor Link

A tool call keeps running on the document service when the caller stops waiting. Send an Idempotency-Key (up to 200 characters, unique per account), and if a call times out, send it again with the same key and body: you get the first call's answer instead of running it twice. Drex waits up to 270 seconds for an answer and then answers 503; retry that the same way. The SDKs and the CLI mint the key and retry for up to 15 minutes on their own.

Each reply's job_id is the job the call ran as, and GET /v1/documents/jobs/{job_id} reads it back. The calls don't appear in Usage › Logs.

ErrorsCopy Anchor Link

Every other error is on Errors.