---
title: Files and paths
description: Understand file identity, logical paths, sources, and metadata.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Files and paths

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

*Illustration: 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**

```json
{
  "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](/engine/reference/list-files) 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](/engine/reference/get-file) 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](/engine/reference/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.
## Sitemap

See the full [sitemap](/sitemap.md) for all pages.