Skip to main content

Common API workflows

This page shows how the public HTTP route families fit together.

Workflow: create a session and render a workspace view​

  1. POST /v1/sessions
  2. GET /v1/sessions/{sessionId}
  3. GET /v1/sessions/{sessionId}/manifest

Use this flow when your product needs to create a workspace and immediately present a browser, review panel, or analysis surface.

Recommended product behavior:

  • Use the session detail response for top-level metadata.
  • Use the manifest response for the tree view.
  • Keep those concerns separate in the UI.

Workflow: create a review branch​

  1. Start from an existing session.
  2. POST /v1/sessions/{sourceSessionId}/fork
  3. Run changes against the fork.
  4. Attach annotations or publish bus messages on the fork.
  5. Request approval or commit only after review.

This is the safest pattern when multiple approaches or reviewers may be involved.

Workflow: mount locally but keep workflow control in HTTP​

This is one of the strongest end-to-end patterns in AetherFS.

  1. Create or select the session over HTTP.
  2. Use Aether CLI to mount that session locally on a user machine.
  3. Let the user edit with local tools.
  4. Use HTTP for annotations, approvals, checkpoints, and commits.

This split works well because:

  • Aether CLI provides the local filesystem experience.
  • HTTP provides the stable control-plane contract.
  • The product does not have to fake local file semantics over REST.

Workflow: mutate filesystem state through the gateway​

Typical route families include:

  • POST /v1/sessions/{sessionId}/dirs
  • DELETE /v1/sessions/{sessionId}/files
  • POST /v1/sessions/{sessionId}/rename
  • POST /v1/sessions/{sessionId}/batch
  • POST /v1/sessions/{sessionId}/patchSegments
  • POST /v1/sessions/{sessionId}/symlinks

Use these routes instead of assuming the gateway provides a plain REST file upload/download model.

Recommended mutation pattern:

  1. Read the current manifest.
  2. Acquire any needed lock state.
  3. Perform the mutation route.
  4. Refresh the relevant manifest scope.
  5. Record review or activity metadata if the change matters to others.

Workflow: coordinate a multi-step agent or tool run​

  1. Create or select a session.
  2. Store derived state in the session cache.
  3. Publish progress messages through the bus.
  4. Record durable review notes as annotations.
  5. Request approval if the workflow requires it.
  6. Commit or checkpoint the result.

Relevant route families:

  • /v1/sessions/{sessionId}/cache/...
  • /v1/sessions/{sessionId}/bus...
  • /v1/sessions/{sessionId}/annotations...
  • /v1/sessions/{sessionId}/request-approval
  • /v1/sessions/{sessionId}/commit

This pattern is especially strong when an automated system produces work that a human must later inspect.

Workflow: checkpoint before a risky change​

  1. POST /v1/sessions/{sessionId}/checkpoints
  2. Perform the risky mutation.
  3. If the result is bad, POST /v1/sessions/{sessionId}/restore

This is the simplest recovery-oriented workflow in the public API.

Good times to use it:

  • before mass rename
  • before import or synchronization
  • before tool-generated patch application
  • before destructive cleanup

Workflow: explicit approval before persistence​

  1. Create or update the session state.
  2. Attach annotations or a commit summary.
  3. POST /v1/sessions/{sessionId}/request-approval
  4. POST /v1/sessions/{sessionId}/approvals/{approvalId}/grant or deny
  5. Only after grant, continue with commit, merge, or source promotion

This pattern is ideal for beta-stage products, risky automation, and any workflow where trust must be earned step by step.

Workflow: promote a good session outcome into a reusable source​

  1. Produce or refine the desired content in a session.
  2. Validate it with your normal review flow.
  3. POST /v1/sources/{sourceId}/promoteSession

Use this when the output should become the next reusable starting point.

This is better than leaving a successful result trapped inside one temporary session when future work should begin from that result.

Workflow: long-running import or source refresh​

  1. Start the source action.
  2. Capture the returned job or operation reference.
  3. Poll /v1/sources/{sourceId}/jobs/{jobId} until completion.
  4. Create or update sessions from the refreshed source as needed.

Use this pattern for imports and source refresh workflows that cannot complete as one immediate request.

Workflow: session health and account visibility​

Use these route families in dashboards, support tooling, or account views:

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

Keep this data separate from workflow content. It belongs in operational or reporting views, not in the filesystem tree.

Workflow: resolve concurrent edits safely​

When several actors may touch the same session:

  1. prefer forks over shared mutation
  2. use lock routes where your workflow needs them
  3. use optimistic-concurrency guards where available
  4. refresh manifest and session detail before retrying

The goal is not to eliminate conflict entirely. The goal is to make conflict visible and recoverable.

Final guidance​

If you are implementing an API client:

  • use these pages for workflow design
  • use the public OpenAPI contract for exact schemas and code generation
  • use Aether CLI when you need local filesystem behavior
  • do not rely on undocumented internal routes or guessed path shapes

See also: