> ## Documentation Index > Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt > Use this file to discover all available pages before exploring further. # locate > 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. ## OpenAPI ````yaml /openapi.json post /v1/workspaces/{workspace_id}/tools/locate openapi: 3.1.0 info: description: >- Document intelligence: parse, split, classify, extract, and ground files, or build a searchable workspace. Authenticate with ``X-API-Key``. title: NDI Platform API version: 0.1.0 servers: - url: https://ndi-api.nace.ai security: [] tags: [] paths: /v1/workspaces/{workspace_id}/tools/locate: post: tags: - tools summary: locate description: >- 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. operationId: locate_v1_workspaces__workspace_id__tools_locate_post parameters: - description: Workspace identifier. in: path name: workspace_id required: true schema: description: Workspace identifier. format: uuid title: Workspace Id type: string - description: >- 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. in: header name: Idempotency-Key required: false schema: anyOf: - maxLength: 200 type: string - type: 'null' description: >- 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. title: Idempotency-Key requestBody: content: application/json: schema: $ref: '#/components/schemas/LocateRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/LocateResponse' description: Successful Response '504': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Gateway Timeout default: content: application/json: example: error: code: invalid_request detail: null message: >- Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false schema: $ref: '#/components/schemas/ErrorEnvelope' description: >- Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code. security: - APIKeyHeader: [] components: schemas: LocateRequest: additionalProperties: false description: >- Request for ``locate``: where in the workspace a piece of information is. The navigator NDI's own agent calls as ``ndi-locate``, over the files the caller may see. It is stateless: what a caller was already offered (``exclude``) and has read (``already_read``) is left out of the answer only when sent back, as a run's memory does it for NDI's agent. A call that leaves out nothing is the caller's opening and rates more files. properties: already_read: description: >- Reads already done: their pieces are left out, and the navigator is told they did not settle the need. items: $ref: '#/components/schemas/LocateRead' maxItems: 1000 title: Already Read type: array every: default: false description: >- 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`. title: Every type: boolean exclude: description: Pieces earlier locates offered, left out of this answer. items: $ref: '#/components/schemas/LocatePiece' maxItems: 1000 title: Exclude type: array k: default: 12 description: How many pieces to name. maximum: 24 minimum: 1 title: K type: integer need: description: >- What is still needed, in a few words: a year, an entity, a line item, a definition. maxLength: 400 minLength: 1 title: Need type: string path_prefix: anyOf: - type: string - type: 'null' description: >- Only files under this folder, workspace-relative; `paths` adds files. Omit both for the whole workspace. title: Path Prefix paths: anyOf: - items: maxLength: 1024 minLength: 1 type: string minItems: 1 type: array - type: 'null' description: >- Only these uploaded files (with `path_prefix`, its folder's files too). Unknown or inaccessible paths are refused. title: Paths question: anyOf: - maxLength: 4096 minLength: 1 type: string - type: 'null' description: >- The whole question the need is part of; every decision weighs the need within it. Omit it and the need is the whole question. title: Question required: - need title: LocateRequest type: object LocateResponse: additionalProperties: false description: >- Response of ``locate``: the reply NDI's agent reads, and the same findings as fields. properties: job_id: anyOf: - format: uuid type: string - type: 'null' description: The external operation job. title: Job Id pages: description: The pieces named, best first. items: $ref: '#/components/schemas/LocatedPiece' title: Pages type: array population: description: >- Set when answering needs every file of a kind (each invoice, every contract): the members, best first. items: $ref: '#/components/schemas/LocatedMember' title: Population type: array population_unrated: default: 0 description: >- 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`. title: Population Unrated type: integer tables: description: The tables rated for the need, best first. items: $ref: '#/components/schemas/LocatedTableRef' title: Tables type: array text: description: >- The reply as NDI's own agent reads it: each piece with the command that reads it and its opening text, then a population's members and the tables to query. title: Text type: string required: - text - pages - tables - population title: LocateResponse type: object ErrorEnvelope: description: Every non-2xx body on ``/v1``. example: error: code: invalid_request detail: null message: Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false properties: error: $ref: '#/components/schemas/Error' required: - error title: ErrorEnvelope type: object LocateRead: additionalProperties: false description: >- A read already done: pages of a paged file, a line span of a text file, or the whole file (neither given). properties: component: anyOf: - maxLength: 1024 type: string - type: 'null' description: >- The tab or section read; null for the file's own text, or every tab of a whole read. title: Component line_end: anyOf: - minimum: 1 type: integer - type: 'null' description: Last line read; null to the end. title: Line End line_start: anyOf: - minimum: 1 type: integer - type: 'null' description: First line read; null from line 1. title: Line Start pages: anyOf: - items: minimum: 1 type: integer maxItems: 1000 minItems: 1 type: array - type: 'null' description: The page numbers that were read. title: Pages path: description: The file's uploaded source path. maxLength: 1024 minLength: 1 title: Path type: string required: - path title: LocateRead type: object LocatePiece: additionalProperties: false description: A piece a previous locate offered, as its `pages[]` entry named it. properties: component: anyOf: - maxLength: 1024 type: string - type: 'null' description: The piece's `component` (a tab or section); null when it had none. title: Component number: description: 'The piece''s `number`: a page, or a text file''s window.' minimum: 1 title: Number type: integer path: description: The file's uploaded source path. maxLength: 1024 minLength: 1 title: Path type: string required: - path - number title: LocatePiece type: object LocatedPiece: additionalProperties: false description: >- A piece the navigator named: a page of a paged document, or a line window of a text file. properties: component: anyOf: - type: string - type: 'null' description: >- The tab or section a read of the piece names; null when the file's text is one. title: Component head: description: The piece's opening text, cut where the reply text cuts it. title: Head type: string line_end: anyOf: - type: integer - type: 'null' description: A window's last line, inclusive. title: Line End line_start: anyOf: - type: integer - type: 'null' description: A window's first line, as read-file numbers lines. title: Line Start number: description: The page number, or the window's number in a text file. title: Number type: integer paged: description: True for a page (read it by `number`); false for a window of lines. title: Paged type: boolean path: description: Uploaded source path of the file. title: Path type: string score: description: How likely the piece holds what is needed, 0 to 1. title: Score type: number required: - path - paged - number - score - head title: LocatedPiece type: object LocatedMember: additionalProperties: false description: A file rated a member when the question needs every file of a kind. properties: path: description: The file's uploaded source path. title: Path type: string score: description: How likely the file is a member, 0 to 1. title: Score type: number required: - path - score title: LocatedMember type: object LocatedTableRef: additionalProperties: false description: A queryable table the navigator rated for the need. properties: columns: description: Every column of the table, in order. items: type: string title: Columns type: array path: description: Uploaded source path of the file holding it. title: Path type: string relevant_columns: description: The columns a query for the need reads, when rated. items: type: string title: Relevant Columns type: array score: description: How likely its rows answer the need, 0 to 1. title: Score type: number sql_table: description: The table's name in SQL queries. title: Sql Table type: string tab: anyOf: - type: string - type: 'null' description: The workbook tab, when it is one. title: Tab required: - sql_table - path - score - columns - relevant_columns title: LocatedTableRef type: object Error: description: The error object, per spec 12 §1.8. properties: code: $ref: '#/components/schemas/ErrorCode' detail: anyOf: - additionalProperties: true type: object - type: 'null' description: Structured payload, when the code carries one. title: Detail message: description: Human- and model-readable; says what to do differently. title: Message type: string request_id: anyOf: - type: string - type: 'null' description: >- Per-request correlation id; matches the ``X-Request-Id`` header. Null only when the error was minted outside any HTTP request, e.g. by a worker. title: Request Id retryable: description: Whether retrying the identical request could succeed. title: Retryable type: boolean required: - code - message - retryable title: Error type: object ErrorCode: description: |- Every error the ``/v1`` surface can return. Clients must treat this as an **open** enum: a new member is an additive change (spec 12 §9), and a client that crashes on an unknown code makes every future error a breaking change. enum: - storage_connection_not_found - storage_connection_in_use - storage_limit_exceeded - storage_conflict - storage_auth_required - storage_unavailable - scan_required - scan_rejected - scan_unavailable - invalid_request - unsupported_file_type - file_too_large - invalid_schema - invalid_sql - invalid_path_prefix - command_not_permitted - batch_too_large - domain_validation_failed - default_label_required - wait_required_for_zero_retention - ledger_decision_invalid - tenant_required - partner_required - workspace_not_found - file_not_found - job_not_found - upload_not_found - node_not_found - schema_not_found - domain_not_found - session_not_found - access_label_not_found - ledger_understanding_not_found - ledger_table_not_found - tenant_not_found - path_conflict - schema_version_conflict - access_label_name_taken - workspace_name_taken - access_label_in_use - upload_expired - file_not_ingested - workspace_deleting - workspace_not_deletable - ingestion_in_progress - job_not_cancellable - confirmation_required - domain_not_published - domain_in_use - reserved_domain_slug - kg_not_built - kg_build_in_progress - ledger_understanding_in_progress - ledger_understanding_version_outdated - session_busy - tenant_limit_reached - range_not_satisfiable - result_expired - access_denied - tenant_disabled - access_backstop_violation - access_mode_not_implemented - rate_limited - concurrency_limit_reached - quota_exceeded - corrupt_file - zero_byte_file - encrypted_file - csv_dialect_ambiguous - csv_parse_failed - parse_failed - ocr_failed - conversion_failed - sheetless_workbook - unplayable_media - unclassified_pages - job_cancelled - job_timeout - upstream_unavailable - internal_error - unauthorized - not_implemented title: ErrorCode type: string securitySchemes: APIKeyHeader: in: header name: X-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.