Skip to main content

Collaboration and oversight

AetherFS is built for workflows where multiple actors may participate in the same session.

Annotations​

Annotation routes include:

  • /v1/sessions/{sessionId}/annotations
  • /v1/sessions/{sessionId}/annotations/{annotationId}

Use annotations for durable, structured notes about a session or its content.

Good uses:

  • Review comments.
  • Labels.
  • Workflow state.
  • Explanations for proposed changes.

File locks​

Collaboration routes for file locking include:

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

Use these when multiple actors might contend for the same path and your product needs explicit coordination.

Approvals​

Approval routes include:

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

These routes let your product enforce explicit human or policy gates before important actions proceed.

A strong review workflow usually looks like this:

  1. Make or propose changes in a session.
  2. Record context with annotations or bus messages.
  3. Request approval.
  4. Grant or deny through the approval routes.
  5. Commit, export, merge, or discard based on the decision.

When to use which surface​

  • Use annotations for durable review metadata.
  • Use file locks for concurrency control around specific paths.
  • Use approvals when a workflow must pause for an explicit decision.