Files and paths

Identity, path, and source

{
  "id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
  "path": "/incidents/checkout.txt",
  "status": "indexing",
  "stage": "engine_queued",
  "source": {
    "type": "inline",
    "content_type": "text/plain",
    "bytes": 118
  },
  "metadata": {
    "environment": "production",
    "service": "checkout"
  },
  "created_at": "2026-10-06T12:00:00Z",
  "updated_at": "2026-10-06T12:00:00Z"
}

Use file.id to identify the result in events, Search hits, and Answer citations. Use path for readable organization and prefix selection. Use source.content_type to declare the content’s media type.

Path rules

Paths are case-sensitive UTF-8 strings. They begin with / and never end with /. A path can contain at most 1,024 UTF-8 bytes. It cannot contain control characters, empty segments, . segments, or .. segments.

/reports/2026/q1.pdf is valid. reports/q1.pdf, /reports//q1.pdf, and /reports/../q1.pdf are invalid. Prefixes ending in / act like directories, but you do not create a folder resource.

A living path is unique within its collection. Adding content at the same path replaces the prior file with a new file ID. Save the replacement ID. A different path identifies another file. The API has no file move operation.

Find a file by path

The file list accepts ?path=/incidents/checkout.txt for an exact lookup. It returns a page with zero or one item. Use ?prefix=/incidents/ for all files below that prefix. Do not send both path and prefix.

The file detail route accepts a file ID or a URL-encoded path. An encoded path begins with %2F. Prefer the exact-path list query when you want to avoid encoding slashes inside a route segment.

Metadata and content

metadata is a JSON object for application facts, such as service name, environment, or a source record ID. Search and Answer filters refer to these fields with names such as metadata.environment. A filter can read only the keys that the collection lists in its metadata fields. Every key is stored and returned with the file.

Metadata is separate from the original file bytes. A file response describes the source; it does not include the original inline text. Get file content returns a short-lived download URL when available.

An external source can return 409 external_source when its connector cannot issue a download URL. In that case, retrieve bytes through your own authorized storage service.