Skip to main content

HTTP API overview

The public HTTP API is the user-facing integration surface for AetherFS.

Base path​

The public routes are versioned under:

/v1

Do not assume /api/v1. The public gateway contract uses /v1/... routes.

Source of truth​

For exact schemas, parameters, and examples, use the generated public OpenAPI reference:

This written guide explains how to think about the API and how the route families fit together.

What the HTTP API covers​

The public HTTP surface is organized around a few core areas:

  • Sessions.
  • Filesystem control and metadata.
  • Checkpoints and commits.
  • Collaboration and approvals.
  • Knowledge cache and message bus.
  • Health, analytics, usage, and metrics.
  • Secrets.
  • Underlay sources.

What the HTTP API is not​

The HTTP gateway is not a generic mirror of every internal or gRPC capability.

In particular:

  • The HTTP surface is a curated public contract.
  • Some broader public service capabilities may exist outside the simple JSON/REST-style route set.
  • You should not invent routes based on internal service names or assumptions.

If a route is not present in the public OpenAPI contract, do not rely on it.

Route families in the public contract​

Session lifecycle​

Examples:

  • /v1/sessions
  • /v1/sessions/{sessionId}
  • /v1/sessions/{sourceSessionId}/fork
  • /v1/sessions/{sessionId}/checkpoints
  • /v1/sessions/{sessionId}/restore
  • /v1/sessions/{sessionId}/commit

Filesystem operations​

Examples:

  • /v1/sessions/{sessionId}/manifest
  • /v1/sessions/{sessionId}/dirs
  • /v1/sessions/{sessionId}/files
  • /v1/sessions/{sessionId}/patchSegments
  • /v1/sessions/{sessionId}/symlinks
  • /v1/sessions/{sessionId}/readSymlink

Messaging and workflow state​

Examples:

  • /v1/sessions/{sessionId}/bus
  • /v1/sessions/{sessionId}/bus:publish
  • /v1/sessions/{sessionId}/cache/{key}
  • /v1/sessions/{sessionId}/events

Review and approvals​

Examples:

  • /v1/sessions/{sessionId}/annotations
  • /v1/sessions/{sessionId}/request-approval
  • /v1/sessions/{sessionId}/approvals/{approvalId}/grant
  • /v1/sessions/{sessionId}/approvals/{approvalId}/deny

Observability and reporting​

Examples:

  • /v1/sessions/{sessionId}/health
  • /v1/sessions/{sessionId}/health/report
  • /v1/sessions/{sessionId}/analytics
  • /v1/usage
  • /v1/metrics/cas

Reusable sources​

Examples:

  • /v1/sources
  • /v1/sources/{sourceId}
  • /v1/sources/{sourceId}/refresh
  • /v1/sources/{sourceId}/startImport
  • /v1/sources/{sourceId}/promoteSession

Slash routes and colon aliases​

The public contract currently includes both slash-style routes such as:

/v1/sessions/{sessionId}/commit

and colon-style aliases such as:

/v1/sessions/{sessionId}:commit

Treat the documented OpenAPI contract as the source of truth for which form your client should call. In general, prefer the ordinary slash routes when both are available in your deployment and tooling.

  1. Read Authentication.
  2. Read Conventions.
  3. Read the route-family pages that match your workflow.
  4. Use the OpenAPI reference for exact field-level integration.