Skip to main content

Integration recipes

These recipes are intentionally high level. Use them to design flows, then use the OpenAPI contract for exact request bodies and responses.

Recipe: build a session browser​

Goal:

  • create a workspace
  • show the tree
  • let the user navigate safely

Routes:

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

Notes:

  • session detail drives the header and metadata panel
  • manifest drives the tree and path list
  • reload manifest after each mutation

Recipe: build a review queue​

Goal:

  • show candidate workspaces
  • attach review context
  • gate persistence on approval

Routes:

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

Notes:

  • use tags and annotations together
  • show summaries before approvals when possible

Recipe: build a safe rename flow​

Goal:

  • let a user rename or restructure paths
  • avoid silent collisions or stale assumptions

Routes:

  • GET /manifest
  • POST /rename
  • optional lock routes

Notes:

  • refresh the relevant subtree immediately after rename
  • use checkpoints for large refactors

Recipe: run an automated analysis pass​

Goal:

  • let a tool inspect a session
  • store derived findings
  • present the results later

Routes:

  • GET /manifest
  • /cache/...
  • /bus
  • /annotations

Notes:

  • use cache for structured derived state
  • use bus for live progress
  • use annotations for durable review notes

Recipe: combine API control with local editing​

Goal:

  • product creates and manages sessions
  • user edits locally
  • review and persistence remain server-driven

Flow:

  1. create or select the session over HTTP
  2. hand the session ID to the user
  3. mount with Aether CLI locally
  4. keep approvals, annotations, checkpoints, and commits in HTTP

Why it works:

  • users get a real local workflow
  • the product keeps a stable control plane
  • the API does not need to mimic a full remote disk interface

Recipe: convert a successful session into a reusable baseline​

Goal:

  • take a winning session result
  • make it the new source for later work

Routes:

  • /commit
  • /promoteSession

Notes:

  • use approval before promotion when the baseline matters widely
  • keep sessions temporary and sources durable