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 – filename, extension, size, content type, and timestamps – using virtual fields in the query API. Virtual field queries require no index configuration; just query with @-prefixed field names like @filename, @extension, or @size.

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 /.config/indexes.json (or a nested variant like /data/.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.
• 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)

Query Parameters

File Response

Status: 200 OK

Headers:

Body: raw file bytes (streamed)

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 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.

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

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"
}

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/

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)
• 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. Scans all .permissions files to find paths where the calling user has group-level 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