NAnace
tools

locate

Changed on

Find the pages and tables that hold a piece of information.

Cost class: medium — a few seconds on a workspace the navigator has seen; the first call after an ingestion change reads the workspace's ingestion outputs first.

A decision model walks the workspace's files, sections and pages (built at ingestion) and names the pieces to read, best first, with the tables to query — the locate NDI's own navigate-mode agent runs. text is that agent's reply, word for word. Only files the key may see are considered, cut to path_prefix / paths.

Stateless: send back the pieces a previous call offered (exclude) and what you have read (already_read) to be shown something new.

post/v1/workspaces/{workspace_id}/tools/locate

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

everyboolean

The need names a kind of file and every one is wanted (each invoice, every statement): the navigator rates each file of that kind and lists the members in population.

kinteger

How many pieces to name.

needstring required

What is still needed, in a few words: a year, an entity, a line item, a definition.

path_prefixstring nullable

Only files under this folder, workspace-relative; paths adds files. Omit both for the whole workspace.

pathsstring[] nullable

Only these uploaded files (with path_prefix, its folder's files too). Unknown or inaccessible paths are refused.

pointerboolean

Name every page in text by its opening lines only. Without it, the best pages come in full, as a task's first locate wants them; later locates pass it, so page text does not pile up in an agent's context.

questionstring nullable

The whole question the need is part of; every decision weighs the need within it. Omit it and the need is the whole question.

Response

Successful Response

creditsinteger nullable

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

job_idstring uuid nullable

The external operation job.

population_unratedinteger

Files in folders rated likely to hold members that the budget ran out before rating: when above 0, population is incomplete; narrow the need to a folder, kind or period and locate again with every.

textstring required

The reply as NDI's own agent reads it: each piece with the command that reads it and its text (the best pages in full, the rest by their opening lines; every page by its opening lines with pointer), then a population's members and the tables to query.

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