Documents

List documents

Returns all documents in the project named in the path.

get/v1/projects/{project_id}/documents

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/documents
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Query parameters

path_prefixstring
Example:/reports/

Only documents filed under this directory. The prefix is a path boundary, not a substring: /reports returns /reports/q1.txt and never /reports-archive/q1.txt, and / selects the whole project. A leading slash is optional and a trailing one is ignored, so reports, /reports and /reports/ are the same filter. % and _ are literal characters, not wildcards.

include_withdrawnboolean

Include withdrawn documents. A withdrawn document leaves every default read and is not in the knowledge index at all — its chunks are dropped when it is withdrawn — so this shows it in the listing but never in a search.

related_tostring
Example:doc_V1StGXR8Z5jdHi6B

Only documents related to this one, on either side of the edge: what it points at, and what points at it. An id with no relations narrows the listing to nothing.

tagsstring[]

Filter by tag pairs, written key:value (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; all must be present with exactly that value.

metadatastring

A MetadataFilter as JSON, url-encoded. It travels as JSON rather than as key:value pairs because the match is exact and a query string cannot otherwise say whether 3 is the number or the string.

limitinteger

Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1 or not an integer it is 400.

offsetinteger

Results to skip. Negative or not an integer it is 400.

Response

List of documents

totalinteger
limitinteger
offsetinteger

Example response

{
  "data": [
    {
      "id": "doc_V1StGXR8Z5jdHi6B",
      "file_id": "file_V1StGXR8Z5jdHi6B",
      "project_id": "proj_V1StGXR8Z5jdHi6B",
      "path": "/reports/q1.txt",
      "filename": "my-doc.txt",
      "content_type": "application/pdf",
      "size": 42,
      "status": "ready",
      "version": 1,
      "content": "The quick brown fox jumps over the lazy dog.",
      "chunk_strategy": "size",
      "chunk_size": 800,
      "chunk_overlap": 120
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.