HTTP routes
Status: target layout. Some routes exist today (
/api/...,/api/doc, SPA static), others are planned (/api/couch,/api/s3,/appmount point, the/index, static docs). This is the intended shape; see webapi.md for what's implemented now.
A single combined container serves everything under one origin (ADR 0002). The webapi is the front door and the only writer to the backends (ADR 0016).
| Path | Serves | Notes |
|---|---|---|
/ | App manifest (machine-readable) | JSON definition of the live app — the agent/automation entrypoint, not a human page. See below. |
/health | Liveness + store reachability | Reports the app version and whether CouchDB is reachable and provisioned. What install polls, and the first thing to check when something looks wrong. |
/api | webapi | The application JSON API (sessions, transcripts, search, enrichment). Stable contract. |
/api/sessions/{id}/turns | Speaker-split turns (per session) | One side of the conversation (?role=user/assistant/…) or all turns, from speaker_split/by_role over full-content chunks (ADR 0027). Empty for sessions logged without couchFullContentChunks. |
/api/turns | Cross-session turns | Every turn of one speaker across all sessions, in time order (?role=user/assistant, optional from/to ISO bounds, limit/skip), from speaker_split/by_role_time. Each turn carries its sessionId/cwd. The corpus for cross-project pattern/repetition analysis. |
/api/search | Full-text search | ?q=… over Meilisearch. Returns hits (session metadata — cwd/model/tools/host, sessions index) and turns (conversation content — turn text with cropped snippets, turns index over chunk.entries[]). Best-effort — enabled: false + empty when Meili is disabled/unreachable. Gated by features.meilisearch (ADR 0009). |
/api/search/reindex | Rebuild the search indexes | POST — clears both indexes and repopulates them from CouchDB (summary docs → sessions, full-content chunk entries → turns), reporting scanned/indexed per index plus any Meilisearch failures. The indexes are derived state. They are kept current two ways — the ingest routes index as they write, and a CouchDB _changes follower catches everything else, including the hook's direct writes — so a rebuild is the reconciliation step rather than the only path: history that predates search, anything the follower missed while down, and a corpus whose index names changed. Unlike the ingest hot path it waits for Meilisearch's asynchronous validation, so a rejected batch is reported rather than looking like a success. Driven by cli reindex. |
/api/docs | Scalar API reference | Renders the published OpenAPI spec (the source of truth for generated clients) via Scalar. |
/api/ingest/* | Curated ingest (writes) | The only write surface for consumers — the hook writes to CouchDB/S3 directly so a session is never lost to a webapi outage (ADR 0016). POST /api/ingest/summary (validated, idempotent upsert), POST /api/ingest/events + POST /api/ingest/chunks (bulk append), PUT /api/ingest/{id}/transcript (blob → S3), DELETE /api/ingest/{id} (drop a session's derived docs so it can be re-ingested; ?blobs=true also removes the transcript). Host-side backfill delivers here. |
/api/couch/* | CouchDB proxy (read-only) | Transparent passthrough to CouchDB's HTTP API — docs + design views as a first-class read surface. Writes are not proxied. |
/api/s3/* | S3 proxy (read-only) | Transparent passthrough to object reads (transcripts, summaries, blobs). Writes go through curated webapi endpoints. |
/app | webui SPA | The React app. Optional — can be disabled without affecting the API. |
/docs | Rendered technical docs | The docs/ tree built into the image by scripts/build-docs.ts; also published as the project site. |
/cli/download | CLI binary | The image bundles the CLI; the webui links here for convenience. |
/ — the app manifest (agent entrypoint)
/ is reserved as a machine-readable manifest, not a UI landing page (the UI is /app) — ADR 0022. It serves a JSON (optionally MDX for prose) definition of everything else about the live app, so another AI agent or tool can bootstrap from one request:
- Routes/endpoints available (a compact pointer to the full OpenAPI at
/api/docs, plus the/api/couch+/api/s3proxies). - Non-secret config the app is running with (a config-serving route).
- Dynamic links the webui consumes (e.g. the Services-menu URLs, so they're not hard-coded in the SPA — #14).
- Version & build info.
- Whatever else an agent needs to use the system.
/api/docs stays the human + OpenAPI surface; / is the compact machine front door. Exact manifest schema TBD.
Backing-service admin UIs
Not served by the app — these are the bundled admin dashboards for the backing services, reached directly (and surfaced as links in the webui Services menu, see configuration.md → servicesMenu):
- CouchDB Fauxton, Garage WebUI, Meilisearch dashboard. In the bundled Docker Compose stack they run alongside the app; when backends are external the links point wherever those services live.
Static docs (Tier 3)
For the public release, docs/ is built to static HTML and served from the same container alongside Swagger + webui + webapi (mount point TBD, e.g. /docs) — see tiers.md → Tier 3 and containers.md.