--- title: "Locate information" method: POST path: "/v1/workspaces/{id}/tools/locate" tags: ["Workspaces"] --- # Locate information `POST /v1/workspaces/{id}/tools/locate` ## Request - Base URL: `https://console.nace.ai` - URL: `https://console.nace.ai/v1/workspaces/{id}/tools/locate` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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-file` call that opens it and its text (the best pages in full unless `pointer` asks for opening lines only), then the tables to query. `text` is that answer as NDI's own search agent reads it; `pages`, `tables` and `population` hold the same as fields. Locate is stateless: send back the pieces earlier calls offered (`exclude`) and what you have read (`already_read`) to be shown something new. The first call after the workspace's files change reads them first and can take a minute or more; a call that times out keeps running, so send it again with the same `Idempotency-Key`. Limited to 150 per account every 10 minutes. Free. ## Path parameters - `id` string, required ## Headers - `Idempotency-Key` string ## Request body - LocateRequest - `need` string, required: What is still needed, in a few words: a year, an entity, a line item, a definition. - `question` string: The whole question the need is part of; every decision weighs the need within it. Leave it out and the need is the whole question. - `k` integer: How many pieces to name. - `every` boolean: The need names a kind of file and every one is wanted (each invoice, every statement): the model rates each file of that kind and lists the members in `population`. - `path_prefix` string: Only files under this folder; `paths` adds files. Leave both out for the whole workspace. - `paths` string[]: Only these files (with `path_prefix`, its folder's files too). An unknown path, or one the key can't read, is refused. - `exclude` LocatePiece[]: Pieces earlier locates offered, left out of this answer. - `path` string, required - `number` integer, required: The piece's `number`. - `component` string, nullable: The piece's `component`; null when it had none. - `already_read` LocateRead[]: Reads already done: their pieces are left out, and the model is told they did not settle the need. - `path` string, required - `pages` integer[], nullable: The pages read. - `line_start` integer, nullable: The first line read; null from line 1. - `line_end` integer, nullable: The last line read; null to the end. - `component` string, nullable: The tab or section read; null for the file's own text, or every tab of a whole read. - `pointer` boolean: Name every page in `text` by its opening lines only. Leave it out and the best pages come in full, as a task's first locate wants them; a task's later locates send it, so page text does not pile up in an agent's context. ## Response `200` The answer. - LocateResponse - `text` string, required: The answer as NDI's own search agent reads it: each piece with the `read-file` call that opens 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. - `pages` LocatedPiece[], required: The pieces named, best first. - `path` string, required - `component` string, nullable: The tab or section a read of the piece names; null when the file's text is one. - `paged` boolean, required: True for a page (read it by `number`); false for a window of lines. - `number` integer, required: The page number, or the window's number in a text file. - `line_start` integer, nullable: A window's first line, as `read-file` numbers lines. - `line_end` integer, nullable: A window's last line, inclusive. - `score` number, required: How likely the piece holds what is needed, 0 to 1. - `head` string, required: The piece's opening text. - `tables` LocatedTable[], required: The tables rated for the need, best first. - `sql_table` string, required: The table's name in `run-sql` queries. - `path` string, required: The file holding it. - `tab` string, nullable: The workbook tab, when it is one. - `score` number, required: How likely its rows answer the need, 0 to 1. - `columns` string[], required: Every column, in order. - `relevant_columns` string[], required: The columns a query for the need reads, when rated. - `population` LocatedMember[], required: Set when the answer needs every file of a kind (each invoice, every contract): the members, best first. - `path` string, required - `score` number, required: How likely the file is a member, 0 to 1. - `population_unrated` integer: Files in folders rated likely to hold members that the budget ran out before rating: above 0, `population` is incomplete; narrow the need to a folder, kind or period and locate again with `every`. - `job_id` string, nullable: The job the call ran as; `GET /v1/documents/jobs/{id}` reads it. ## Other responses - `401`: Missing or invalid API key (`authentication_error`, code `invalid_api_key`). - `403`: A `paths` entry names a file the key can't read (`permission_error`, code `access_denied`). - `404`: No workspace with this id that the key may use (`not_found_error`, code `workspace_not_found`), or Workspaces are off on this deployment (`not_found`). - `422`: The body is invalid, or the document service refused it (`invalid_request_error`); the message says why. The workspace is checked first, so an id the key can't use answers `404` whatever the body. - `429`: Over the account's requests per minute, or over 150 locates per account every 10 minutes (`rate_limit_error`, code `rate_limited`). - `500`: Something failed on Drex's side (`internal_error`). - `502`: The document service refused Drex's own request (`upstream_error`, code `ndi_refused_drex`). Retry later. - `503`: The document service is unavailable, or did not answer in time (`service_unavailable`). Retry with the same `Idempotency-Key`. - `504`: The document service timed out (`upstream_error`). Retry with the same `Idempotency-Key`. --- [API](https://skmtc.dev/nace/apis/drex-api.md) - [All operations](https://skmtc.dev/nace/apis/drex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/drex-api/revisions/a0e62d925a61?raw)