---
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",
  "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](/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 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](/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.