Skip to main content

Filesystem routes

The HTTP gateway exposes a public filesystem control surface, but it is not a generic “every file operation as a simple REST route” API.

That distinction matters.

What the HTTP surface is good for​

The current public HTTP contract is especially good for:

  • Tree and manifest inspection.
  • Directory and path operations.
  • Structured mutation actions.
  • Symlink and metadata operations.
  • Locking and coordination around paths.
  • Session-scoped filesystem workflows that need explicit control rather than raw local file semantics.

Discovery first: manifest-driven clients​

The main discovery route is:

  • GET /v1/sessions/{sessionId}/manifest

This should be the foundation for most HTTP clients.

Use it to:

  • Build tree browsers.
  • Explore a subtree before deciding what to mutate.
  • Retrieve metadata without assuming a separate file-download route exists in HTTP.
  • Drive change previews and review UIs.

For most products, the right model is:

  1. Fetch manifest data.
  2. Let the user choose an action.
  3. Call the corresponding mutation route.
  4. Refresh manifest data again.

Directory operations​

Directory routes include:

  • POST /v1/sessions/{sessionId}/dirs
  • DELETE /v1/sessions/{sessionId}/dirs

Use these for:

  • Creating directories before writing or moving content.
  • Removing empty or workflow-specific directories.
  • Building browser-style UIs that need explicit path management.

File deletion​

The delete route is:

  • DELETE /v1/sessions/{sessionId}/files

This route is path-oriented rather than a generic /files/{path} resource route. In the current gateway implementation, it uses request parameters such as the target path and optional optimistic-concurrency data.

That design is intentional. It keeps deletion aligned with the broader session-scoped action model instead of pretending every path is a stable first-class REST resource.

Path-shape operations include:

  • POST /v1/sessions/{sessionId}/rename
  • POST /v1/sessions/{sessionId}:link
  • POST /v1/sessions/{sessionId}:unlink

Use them when your workflow needs to change path layout without treating the whole filesystem as an object store.

Typical uses:

  • Rename flows in a file browser.
  • Workflow-driven path normalization.
  • Linking or unlinking content as part of a higher-level transformation.

Batch mutation​

The public contract includes:

  • POST /v1/sessions/{sessionId}/batch

Use batch operations when your client needs to coordinate several mutations as one higher-level step.

Good uses:

  • Multi-path cleanup.
  • Rename-plus-create flows.
  • Small structured edits that should be issued together.

Batch is especially useful for reducing round trips and keeping a UI action aligned with one server-side intent.

Segment and extent-oriented mutation​

The public contract includes:

  • POST /v1/sessions/{sessionId}/patchSegments
  • POST /v1/sessions/{sessionId}/seekHoleData
  • POST /v1/sessions/{sessionId}:getCasExtents
  • POST /v1/sessions/{sessionId}/fallocate

These routes exist for clients that need more control than simple whole-file replacement semantics.

They are useful when you need to:

  • Apply partial updates.
  • Preserve sparse structure.
  • Reason about content layout and extents.
  • Build advanced editors or synchronization tools.

Symlink routes include:

  • GET /v1/sessions/{sessionId}/symlinks
  • POST /v1/sessions/{sessionId}/symlinks
  • GET /v1/sessions/{sessionId}/readSymlink

Use them to:

  • Enumerate symlink state.
  • Create symlinks in a controlled, explicit way.
  • Resolve and inspect a symlink target in product workflows.

Extended attributes and locks​

Path metadata routes include:

  • /v1/sessions/{sessionId}:getXattr
  • /v1/sessions/{sessionId}:listXattrs
  • /v1/sessions/{sessionId}:setXattr
  • /v1/sessions/{sessionId}:removeXattr
  • /v1/sessions/{sessionId}:getPosixLock
  • /v1/sessions/{sessionId}:setPosixLock
  • /v1/sessions/{sessionId}:setPosixLockBlocking
  • /v1/sessions/{sessionId}:flock
  • /v1/sessions/{sessionId}:funlock

Use these when your workflow needs more than plain content mutation:

  • Preserve metadata that tools care about.
  • Coordinate concurrent access to specific paths.
  • Build workflows that need explicit lock state before a write or handoff.

File-collaboration lock routes​

The broader public API also includes higher-level collaboration lock routes under:

  • /v1/sessions/{sessionId}/files/lock
  • /v1/sessions/{sessionId}/files/unlock
  • /v1/sessions/{sessionId}/files/renew-lock
  • /v1/sessions/{sessionId}/files/list-locks
  • /v1/sessions/{sessionId}/files/force-unlock

These are useful when your product needs collaboration semantics around files rather than only POSIX-style lock behavior.

Important boundary: no fake REST file API​

Do not assume the public HTTP contract supports generic routes like:

  • GET /v1/sessions/{sessionId}/files/{path}
  • PUT /v1/sessions/{sessionId}/files/{path}

Those are not the right mental model for the current public HTTP gateway.

The correct model is:

  • manifest for inspection
  • action routes for mutation
  • Aether CLI for local filesystem semantics
  • the OpenAPI contract for exact request shapes

When to use HTTP versus Aether CLI​

Use the HTTP filesystem routes when you need:

  • Product or service integration.
  • Controlled path-oriented actions.
  • Review and workflow metadata around mutations.
  • Tree inspection without a mount.

Use Aether CLI when you need:

  • Local editor and shell workflows.
  • Real local path semantics.
  • User-managed interactive work on a machine they control.

Use both when:

  • a product manages sessions over HTTP
  • a user edits locally through Aether CLI
  • persistence and approval still happen through the API

See also: