Files and paths

AI Draft

Understand file identity, logical paths, sources, and metadata.

A file is one item of content in a collection. Its ID identifies the resource. Its path organizes the collection. Its source tells Engine how to obtain the content.

Identity, path, and source

checkout.txttext/plain

Identity: fil_…; Stable reference in results and events
Logical path: /incidents/checkout.txt; Unique within its collection
Source: inline · upload · uri; Where the content comes from
Metadata: environment: production; Facts your application can filter

One file has an immutable fil_ identifier, the logical path /incidents/checkout.txt, a content source, and application metadata. The path is not a storage URI.

Example file resource

{
  "id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
  "path": "/incidents/checkout.txt",
  "status": "indexing",
  "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 Query 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 Query filters refer to these fields with names such as metadata.environment.

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.

Was this page helpful?