Files & Directories

AeorDB exposes a content-addressable filesystem through its file routes. Every path under /files/ represents either a file or a directory.

Endpoint Summary

Searching by metadata: Files can also be searched by their metadata – path, filename, extension, hash, size, content type, and timestamps – using virtual fields in the query API. New databases index these fields by default; legacy databases can add the default config and reindex. If a virtual-field index is absent, AeorDB falls back to a FileRecord metadata scan.

PUT /files/

Store a file at the given path. Parent directories are created automatically. If a file already exists at the path, it is overwritten (creating a new version).

Streaming uploads: Files are streamed in 256 KB chunks – the server never buffers the full file in memory. Files up to the router-level limit (10 GB) are supported. For resumable uploads of very large files, see the chunked upload protocol.

Request

• Headers:
  • Authorization: Bearer <token> (required)
  • Content-Type (optional) – auto-detected from magic bytes if omitted
• Body: raw file bytes

Response

Status: 201 Created

{
  "path": "/data/report.pdf",
  "content_type": "application/pdf",
  "size": 245678,
  "created_at": 1775968398000,
  "updated_at": 1775968398000
}

Side Effects

• If the path matches /.aeordb-config/indexes.json (or a nested variant like /data/.aeordb-config/indexes.json), a reindex task is automatically enqueued for the parent directory. Any existing pending or running reindex for that path is cancelled first. Configs containing only virtual @ metadata fields use metadata-only reindexing automatically.
• Triggers entries_created events on the event bus.
• Runs any deployed store-phase plugins.

Example

curl -X PUT http://localhost:6830/files/data/report.pdf \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

Error Responses

GET /files/

Read a file or list a directory. The server determines the type automatically:

• If the path resolves to a file, the file content is streamed with appropriate headers.
• If the path resolves to a directory, a JSON object with an items array of children is returned.

Request

• Headers:
  • Authorization: Bearer <token> (required)
  • Range: bytes=<start>-<end> (optional for file reads) – single byte ranges only

Query Parameters

File Response

Status: 200 OK for full reads, 206 Partial Content for valid byte-range reads

Headers:

Body: raw file bytes (streamed)

Byte Range Reads

File reads support HTTP single byte ranges for browser media seeking and partial downloads:

curl http://localhost:6830/files/media/movie.mp4 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Range: bytes=1048576-2097151" \
  -o movie.part

Supported forms:

Unsatisfiable or malformed byte ranges return 416 Range Not Satisfiable with Content-Range: bytes */<file_size>. Multi-range requests are not supported.

Directory Response

Status: 200 OK

Each entry includes path, hash, and numeric entry_type fields. Symlink entries also include a target field.

Entry types: 2 = file, 3 = directory, 8 = symlink.

Effective permissions: When a directory listing is accessed with a scoped API key or as a non-root user, each item in the response includes an effective_permissions field – an 8-character crudlify string indicating what operations the caller can perform on that item. Ancestor directory items (directories leading to the scoped path) receive read+list permissions only.

{
  "items": [
    {
      "path": "/data/report.pdf",
      "name": "report.pdf",
      "entry_type": 2,
      "hash": "a3f8c1...",
      "size": 245678,
      "created_at": 1775968398000,
      "updated_at": 1775968398000,
      "content_type": "application/pdf"
    },
    {
      "path": "/data/images",
      "name": "images",
      "entry_type": 3,
      "hash": "b2c4d5...",
      "size": 0,
      "created_at": 1775968000000,
      "updated_at": 1775968000000,
      "content_type": null
    },
    {
      "path": "/data/latest",
      "name": "latest",
      "entry_type": 8,
      "hash": "c3d5e6...",
      "target": "/data/report.pdf",
      "size": 0,
      "created_at": 1775968500000,
      "updated_at": 1775968500000,
      "content_type": null
    }
  ]
}

Paginated Directory Listing

Use limit and offset to paginate directory listings:

curl "http://localhost:6830/files/data/?limit=10&offset=20" \
  -H "Authorization: Bearer $TOKEN"

When limit or offset is provided, the response includes pagination metadata:

{
  "items": [...],
  "total": 150,
  "limit": 10,
  "offset": 20
}

Examples

Read a file:

curl http://localhost:6830/files/data/report.pdf \
  -H "Authorization: Bearer $TOKEN" \
  -o report.pdf

List a directory:

curl http://localhost:6830/files/data/ \
  -H "Authorization: Bearer $TOKEN"

Recursive Directory Listing

Use the depth and glob query parameters to list files recursively:

# List all files recursively
curl http://localhost:6830/files/data/?depth=-1 \
  -H "Authorization: Bearer $TOKEN"

# List only .psd files anywhere under /assets/
curl "http://localhost:6830/files/assets/?depth=-1&glob=*.psd" \
  -H "Authorization: Bearer $TOKEN"

# List JSON frames anywhere under /sessions/
curl "http://localhost:6830/files/sessions/?depth=-1&glob=**/frames/*.json" \
  -H "Authorization: Bearer $TOKEN"

# List one level deep
curl http://localhost:6830/files/data/?depth=1 \
  -H "Authorization: Bearer $TOKEN"

When depth > 0 or depth = -1, the response contains files only in a flat list. Directory entries are traversed but not included in the output. Recursive globs can match a basename (*.psd), a path relative to the requested directory (**/frames/*.json), or a full path.

Versioned Reads

Read a file as it was at a specific snapshot or version:

# Read file at a named snapshot
curl "http://localhost:6830/files/data/report.pdf?snapshot=v1.0" \
  -H "Authorization: Bearer $TOKEN"

# Read file at a specific version hash
curl "http://localhost:6830/files/data/report.pdf?version=a1b2c3..." \
  -H "Authorization: Bearer $TOKEN"

If both snapshot and version are provided, snapshot takes precedence. Returns 404 if the file did not exist at that version.

Error Responses

POST /files/fetch

Fetch multiple files or multiple file ranges in one request. There are two request shapes:

• paths: whole-file batch fetch, returned as a JSON object keyed by canonical path.
• items: range batch fetch, returned as an ordered items array.

Provide either paths or items, not both. Directories, missing files, system paths, and unreadable paths return 404. File bytes are encoded into JSON strings with UTF-8 lossy conversion, so binary data may contain replacement characters.

Request

• Headers:
  • Authorization: Bearer <token> (required)
  • Content-Type: application/json (required)
• Body:

{
  "paths": [
    "/data/a.txt",
    "/data/b.json"
  ],
  "max_bytes": 1048576
}

Response

Status: 200 OK

{
  "/data/a.txt": {
    "path": "/data/a.txt",
    "name": "a.txt",
    "size": 324534,
    "created_at": 1235413451345,
    "updated_at": 134513453145,
    "content_type": "text/plain",
    "content": "..."
  },
  "/data/b.json": {
    "path": "/data/b.json",
    "name": "b.json",
    "size": 2048,
    "created_at": 1235413451345,
    "updated_at": 134513453145,
    "content_type": "application/json",
    "content": "{\"ok\":true}"
  }
}

Range Fetch Mode

Use items to fetch line, character, byte, or JSON Pointer ranges. This is the preferred follow-up for search hit locators.

{
  "items": [
    {
      "id": "hit-1",
      "path": "/data/a.txt",
      "if_content_hash": "b3c1...",
      "range": { "mode": "lines", "start": 10, "end": 14 }
    },
    {
      "id": "hit-2",
      "path": "/data/b.json",
      "if_updated_at": 1775968398000,
      "range": { "mode": "json_pointer", "pointer": "/messages/0/content" },
      "max_bytes": 65536
    }
  ],
  "continue_on_error": true
}

Range-mode response:

{
  "items": [
    {
      "id": "hit-1",
      "status": "ok",
      "path": "/data/a.txt",
      "name": "a.txt",
      "size": 324534,
      "created_at": 1235413451345,
      "updated_at": 134513453145,
      "content_hash": "b3c1...",
      "content_type": "text/plain",
      "range": { "mode": "lines", "start": 10, "end": 14, "pointer": null },
      "source_size": 324534,
      "content": "...",
      "truncated": false
    }
  ],
  "has_errors": false
}

If continue_on_error is true, per-item errors have status values such as not_found, stale, invalid, too_large, or error.

Limits

Example

curl -X POST http://localhost:6830/files/fetch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paths":["/data/a.txt","/data/b.json"]}'

Error Responses

DELETE /files/

Delete a file or empty directory at the given path. Creates a DeletionRecord and removes the entry from its parent directory listing. The handler tries file deletion first, then directory deletion, then returns 404. Non-empty directories return 400 with “Directory is not empty (N children)”.

Request

• Headers:
  • Authorization: Bearer <token> (required)

Response

Status: 200 OK

{
  "deleted": true,
  "path": "/data/report.pdf"
}

Deleted File Access

Deleted files are invisible to users who lack the d (delete) permission on the containing directory:

• GET /files/deleted?path=/dir returns an empty list
• GET /files/{path} returns 404 for deleted files
• HEAD /files/{path} returns 404 for deleted files
• Reading a deleted file via ?version= also returns 404

Root users always have full access to deleted files.

Side Effects

• Triggers entries_deleted events on the event bus.
• Updates index entries for the deleted file.

Example

curl -X DELETE http://localhost:6830/files/data/report.pdf \
  -H "Authorization: Bearer $TOKEN"

Error Responses

PATCH /files/

PATCH is overloaded by Content-Type:

• application/json → rename the file or symlink (documented below).
• application/merge-patch+json → server-side JSON merge into the stored document. See the dedicated JSON Merge Patch reference for that mode.

The content-type alone discriminates — a merge-patch body that happens to contain a "to" key will be merged into the file, not used as a rename instruction.

Rename mode

Rename or move a file or symlink to a new path. This is a metadata-only operation – no data is copied in the content-addressed store. The file’s content hash remains the same; only the path mapping changes.

Request

• Headers:
  • Authorization: Bearer <token> (required)
  • Content-Type: application/json (required — application/merge-patch+json routes to the merge endpoint instead)
• Body:

{
  "to": "/new/path/report.pdf"
}

Response

Status: 200 OK

{
  "from": "/data/report.pdf",
  "to": "/archive/report.pdf"
}

Side Effects

• Triggers entries_created and entries_deleted events on the event bus.
• If the path is a symlink, the symlink itself is moved (not the target).
• If a file already exists at the destination path, the operation fails.

Example

# Move a file
curl -X PATCH http://localhost:6830/files/data/report.pdf \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "/archive/report.pdf"}'

# Rename a symlink
curl -X PATCH http://localhost:6830/files/latest-logo \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "/current-logo"}'

Error Responses

Symlinks

AeorDB supports soft symlinks — entries that point to another path. Symlinks are transparent by default: reading a symlink path returns the target’s content.

PUT /links/

Create or update a symlink.

Request Body:

{
  "target": "/assets/logo.psd"
}

Response: 201 Created

{
  "path": "/latest-logo",
  "target": "/assets/logo.psd",
  "entry_type": 8,
  "created_at": 1775968398000,
  "updated_at": 1775968398000
}

The target path does not need to exist at creation time (dangling symlinks are allowed).

Reading Symlinks

By default, GET /files/{path} follows symlinks transparently:

# Returns the content of /assets/logo.psd
curl http://localhost:6830/files/latest-logo \
  -H "Authorization: Bearer $TOKEN"

To inspect the symlink itself without following it, use ?nofollow=true:

curl "http://localhost:6830/files/latest-logo?nofollow=true" \
  -H "Authorization: Bearer $TOKEN"

Returns the symlink metadata as JSON instead of the target’s content.

Symlink Resolution

Symlinks can point to other symlinks — chains are followed recursively. AeorDB detects cycles and enforces a maximum resolution depth of 32 hops.

HEAD on Symlinks

HEAD /files/{path} returns symlink metadata as headers:

X-AeorDB-Entry-Type: symlink
X-AeorDB-Symlink-Target: /assets/logo.psd
X-AeorDB-Path: /latest-logo
X-AeorDB-Created-At: 1775968398000
X-AeorDB-Updated-At: 1775968398000

Deleting Symlinks

DELETE /files/{path} on a symlink deletes the symlink itself, not the target:

curl -X DELETE http://localhost:6830/files/latest-logo \
  -H "Authorization: Bearer $TOKEN"

{
  "deleted": true,
  "path": "latest-logo",
  "entry_type": "symlink"
}

Symlinks in Directory Listings

Symlinks appear in directory listings with entry_type: 8 and a target field:

{
  "path": "/data/latest",
  "name": "latest",
  "entry_type": 8,
  "hash": "c3d5e6...",
  "target": "/data/report.pdf",
  "size": 0,
  "created_at": 1775968500000,
  "updated_at": 1775968500000,
  "content_type": null
}

Symlink Versioning

Symlinks are versioned like files. Snapshots capture the symlink’s target path at that point in time. Restoring a snapshot restores the link, not the resolved content.

Sharing

AeorDB supports sharing files and directories with specific users and groups. Shares are stored as .permissions files in the filesystem — the sharing API is a convenience layer on top of the existing permission system.

POST /files/share

Share one or more paths with users and/or groups. For files, the permission is scoped to just that file using a path_pattern. For directories, the permission applies to everything inside.

Auth: Root only.

Request Body:

{
  "paths": ["/photos/sunset.jpg", "/photos/beach.jpg"],
  "users": ["6f94eecf-b136-47b4-9b47-c20f781f1f5b"],
  "groups": ["design-team"],
  "permissions": "crudl..."
}

At least one of users or groups must be non-empty.

Response: 200 OK

{
  "shared": 2,
  "paths": ["/photos/sunset.jpg", "/photos/beach.jpg"]
}

How it works:

• For each file path, a PermissionLink is created on the parent directory’s .permissions file with a path_pattern matching the filename — so the permission only applies to that specific file.
• For each directory path, the link is created with no path_pattern — it applies to everything in the directory.
• If a link for the same group and pattern already exists, it is updated (not duplicated).

Example:

curl -X POST http://localhost:6830/files/share \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["/photos/sunset.jpg"],
    "users": ["6f94eecf-b136-47b4-9b47-c20f781f1f5b"],
    "permissions": "cr..l..."
  }'

GET /files/shares

List active shares for a path.

Query Parameters:

Response: 200 OK

{
  "path": "/photos/sunset.jpg",
  "shares": [
    {
      "group": "user:6f94eecf-...",
      "username": "alice",
      "allow": "cr..l...",
      "deny": "........",
      "path_pattern": "sunset.jpg"
    },
    {
      "group": "design-team",
      "allow": "crudl...",
      "deny": "........",
      "path_pattern": null
    }
  ]
}

For user:{uuid} groups, the username field is resolved from the user store. For named groups, username is null.

When querying a specific file, only shares with a matching path_pattern (or directory-wide shares with no pattern) are returned.

Example:

curl "http://localhost:6830/files/shares?path=/photos/sunset.jpg" \
  -H "Authorization: Bearer $TOKEN"

DELETE /files/shares

Revoke a specific share by removing the matching PermissionLink.

Auth: Root only.

Request Body:

{
  "path": "/photos/sunset.jpg",
  "group": "user:6f94eecf-...",
  "path_pattern": "sunset.jpg"
}

Response: 200 OK

{
  "revoked": true,
  "group": "user:6f94eecf-..."
}

Example:

curl -X DELETE http://localhost:6830/files/shares \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/photos/sunset.jpg",
    "group": "user:6f94eecf-...",
    "path_pattern": "sunset.jpg"
  }'

Error Responses (Sharing)

Link Sharing

Shareable URLs backed by scoped API keys. A share link bundles a scoped API key with a JWT token into a URL that opens the portal file browser, scoped to the shared path.

POST /files/share-link

Create a share link for one or more paths. This creates a scoped API key with user_id: null and generates a JWT token embedded in the URL.

Auth: Root only.

Request Body:

{
  "paths": ["/photos/vacation"],
  "permissions": "cr..l...",
  "expires_in_days": 30,
  "base_url": "https://files.example.com"
}

Response: 201 Created

{
  "url": "https://files.example.com/share?token=eyJ...",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "key_id": "a1b2c3d4-...",
  "permissions": "cr..l...",
  "expires_at": 1778560398000,
  "paths": ["/photos/vacation"]
}

The URL opens the portal file browser scoped to the shared path. Ancestor directories are navigable (read+list only) – only path components leading to the target are visible.

Example:

curl -X POST http://localhost:6830/files/share-link \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["/photos/vacation"],
    "permissions": "-r--l---",
    "expires_in_days": 7,
    "base_url": "https://files.example.com"
  }'

GET /files/share-links

List active share links for a path.

Auth: Root only.

Query Parameters:

Response: 200 OK

{
  "path": "/photos/vacation",
  "links": [
    {
      "key_id": "a1b2c3d4-...",
      "label": "share-link:/photos/vacation",
      "permissions": "-r--l---",
      "expires_at": 1778560398000,
      "created_at": 1775968398000
    }
  ]
}

Example:

curl "http://localhost:6830/files/share-links?path=/photos/vacation" \
  -H "Authorization: Bearer $TOKEN"

DELETE /files/share-links/

Revoke a share link. This deletes the underlying scoped API key and invalidates the JWT.

Auth: Root only.

Response: 200 OK

{
  "revoked": true,
  "key_id": "a1b2c3d4-..."
}

Example:

curl -X DELETE http://localhost:6830/files/share-links/a1b2c3d4-... \
  -H "Authorization: Bearer $TOKEN"

Error Responses (Link Sharing)

Shared With Me

GET /files/shared-with-me

List paths that have been shared with the current user. AeorDB resolves the caller’s group memberships against the cached grants index, returning paths where those groups have access. This is used by the portal to discover entry points when the user has no root-level permissions.

Auth: Requires a user-bound token. Share tokens receive 403. Root users receive an empty list (they already have access to everything).

Response: 200 OK

{
  "paths": [
    {
      "path": "/photos/vacation/",
      "permissions": ".r..l...",
      "path_pattern": null
    }
  ]
}

Each entry includes the shared path, the permissions string granted, and an optional path_pattern (non-null when the share targets a specific file within a directory).

Example:

curl http://localhost:6830/files/shared-with-me \
  -H "Authorization: Bearer $TOKEN"

Error Responses:

HEAD /files/

Check whether a path exists and retrieve its metadata as response headers, without downloading the body. Works for both files and directories.

Request

• Headers:
  • Authorization: Bearer <token> (required)

Response

Status: 200 OK (empty body)

Headers:

Example

curl -I http://localhost:6830/files/data/report.pdf \
  -H "Authorization: Bearer $TOKEN"

HTTP/1.1 200 OK
X-AeorDB-Entry-Type: file
X-AeorDB-Path: /data/report.pdf
X-AeorDB-Size: 245678
X-AeorDB-Created-At: 1775968398000
X-AeorDB-Updated-At: 1775968398000
Content-Type: application/pdf

Error Responses

POST /files/copy

Copy files or directories to a new location. Uses content-addressed deduplication — no data is physically duplicated.

Request

• Headers:
  • Authorization: Bearer <token> (required)
  • Content-Type: application/json (required)
• Body:

{
  "paths": ["/src/file1.txt", "/src/file2.txt"],
  "destination": "/dst/"
}

Response

Status: 200 OK

{
  "copied": ["/dst/file1.txt", "/dst/file2.txt"]
}

For directories in the paths list, all contents are recursively copied. If any individual copy fails, the error is reported in an errors array but other copies continue.

Example

curl -X POST http://localhost:6830/files/copy \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["/src/file1.txt", "/src/file2.txt"],
    "destination": "/dst/"
  }'

Global Search

POST /files/search

Search across all indexed directories in the database. Unlike POST /files/query which targets a single directory, global search fans out across every directory that has indexes.

Request body:

{
  "query": "hero-banner",
  "limit": 20,
  "offset": 0
}

The query field performs a broad fuzzy search across default-indexed text metadata fields that have fuzzy-capable indexes, such as @filename and @path.

For more targeted searches, use a structured where clause:

{
  "where": {
    "field": "@filename",
    "op": "similar",
    "value": "hero",
    "threshold": 0.3
  },
  "limit": 20
}

To find every path under a root that contains a file with a known whole-file content hash, query @hash with eq:

{
  "path": "/some/root/",
  "where": {
    "field": "@hash",
    "op": "eq",
    "value": "b3c1..."
  },
  "limit": 1000
}

@hash is the raw whole-file hash (blake3(file bytes)) stored in the FileRecord at write time. It is not the first chunk hash. New databases bootstrap an exact string index for @hash; trigram hash indexes are not created by default because exact hash lookup is the normal use case and trigram hash indexes consume substantial memory on large databases. Existing databases may need their /.aeordb-config/indexes.json updated and reindexed before @hash eq uses only the exact index; reindexing also retires old hash index strategies that are no longer present in the config. Legacy FileRecord v0 entries written before this field existed must be migrated before they can participate in exact @hash lookup; trigger a forced reindex with POST /system/tasks/reindex and "force": true to backfill them.

For agent workflows, /files/search and /files/query also support opt-in hit locators with include_matches: true. Locator responses include snippets, typed ranges, content_hash identity anchors, and fetch hints that can be used with /files/fetch range mode. See Querying for the full schema.

Response:

{
  "results": [
    {
      "path": "/assets/hero-banner.png",
      "score": 0.85,
      "directory": "/assets",
      "index_field": "@filename"
    }
  ],
  "total": 1,
  "directories_searched": 42
}