From ad6fbe326a943f48024e5a85b601b5b56bd0547d Mon Sep 17 00:00:00 2001 From: technical-writer Date: Tue, 2 Jun 2026 08:04:33 -0700 Subject: [PATCH] docs(api-reference): accuracy pass vs real router + dedup Audit Ledger MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Diffed every documented endpoint against the real route table in workspace-server/internal/router/router.go (174 routes, group prefixes resolved). Found 5 documented endpoints that DON'T exist in the router, plus a duplicated section: - DELETE /workspaces/:id/memories/:id → real is the v2 path DELETE /workspaces/:id/v2/memories/:memoryId. Also added the two undocumented v2 reads (GET /v2/namespaces, GET /v2/memories). - GET /workspaces/:id/shared-context → no such route; removed. - GET /admin/workspaces/:id/test-token → that unauthenticated route was removed (2026-04 changelog); replaced with the real POST /admin/workspaces/:id/tokens (AdminAuth) mint endpoint. - POST /workspaces/:id/expand + /collapse → no such routes (canvas expand/collapse is client/viewport state now); removed the fabricated 'Teams' API section. - Two '## Audit Ledger' sections (duplicate #audit-ledger anchor) with conflicting schemas. Kept the canonical HMAC-chain / EU-AI-Act version; removed the stale entries/cursor duplicate; promoted the real Session Search endpoint to its own H2. - Added GET/PUT /workspaces/:id/model + /provider to Configuration (real, were missing). Post-fix: documented-vs-router diff = 0 stale; no duplicate H2 headings; build green. (Many admin/internal/canvas routes remain intentionally undocumented — separate scope.) Co-Authored-By: Claude Opus 4.8 (1M context) --- content/docs/api-reference.mdx | 64 ++++++---------------------------- 1 file changed, 10 insertions(+), 54 deletions(-) diff --git a/content/docs/api-reference.mdx b/content/docs/api-reference.mdx index 5148985..0cd8680 100644 --- a/content/docs/api-reference.mdx +++ b/content/docs/api-reference.mdx @@ -207,6 +207,10 @@ Peer discovery and access control verification. |--------|------|------|-------------| | GET | `/workspaces/:id/config` | WorkspaceAuth | Get the workspace's `config.yaml` contents. | | PATCH | `/workspaces/:id/config` | WorkspaceAuth | Update the workspace config. "Save & Restart" writes config and auto-restarts; "Save" writes only and shows a restart banner in the Canvas. | +| GET | `/workspaces/:id/model` | WorkspaceAuth | Get the workspace's current model selection. | +| PUT | `/workspaces/:id/model` | WorkspaceAuth | Set the workspace model (e.g. `anthropic:claude-sonnet-4-6`). | +| GET | `/workspaces/:id/provider` | WorkspaceAuth | Get the resolved LLM provider for the workspace's runtime + model. | +| PUT | `/workspaces/:id/provider` | WorkspaceAuth | Override the LLM provider for the workspace. | --- @@ -251,7 +255,9 @@ Legacy aliases `GET/POST/DELETE /admin/secrets[/:key]` also exist and behave ide |--------|------|------|-------------| | GET | `/workspaces/:id/memories` | WorkspaceAuth | List or search agent memories. Supports `?q=` for semantic search (see below). | | POST | `/workspaces/:id/memories` | WorkspaceAuth | Create an agent memory entry. | -| DELETE | `/workspaces/:id/memories/:id` | WorkspaceAuth | Delete an agent memory by ID. | +| GET | `/workspaces/:id/v2/namespaces` | WorkspaceAuth | List the HMA memory namespaces visible to this workspace (LOCAL / TEAM / GLOBAL scopes resolved along the org hierarchy). | +| GET | `/workspaces/:id/v2/memories` | WorkspaceAuth | List agent memories via the v2 namespace-scoped API. | +| DELETE | `/workspaces/:id/v2/memories/:memoryId` | WorkspaceAuth | Delete an agent memory by its ID (v2 API). | #### Semantic search (`?q=`) @@ -297,7 +303,6 @@ Workspace file management. Files are stored in the workspace's config directory. | GET | `/workspaces/:id/files/*path` | WorkspaceAuth | Read a specific file. | | PUT | `/workspaces/:id/files/*path` | WorkspaceAuth | Write a file. Creates parent directories as needed. On SaaS workspaces (EC2, no Docker), routes via EC2 Instance Connect endpoint using an ephemeral SSH key pair — the key is scoped to the file-write operation and deleted within 30 seconds. Max payload ~10 MiB. Self-hosted Docker workspaces write via `docker cp` as before. | | DELETE | `/workspaces/:id/files/*path` | WorkspaceAuth | Delete a file. | -| GET | `/workspaces/:id/shared-context` | WorkspaceAuth | Get the shared context files for a workspace (aggregated from parent hierarchy). | --- @@ -313,45 +318,7 @@ Activity logging and search for A2A communications, task updates, and agent logs --- -## Audit Ledger - -Tamper-evident audit trail for workspace events. Used by the Canvas Audit Trail panel. - -| Method | Path | Auth | Description | -|--------|------|------|-------------| -| GET | `/workspaces/:id/audit` | WorkspaceAuth | List audit entries for a workspace. Supports `?event_type=delegation\|decision\|gate\|hitl`, `?cursor=`, and `?limit=` (default 50). | - -### Audit entry schema - -| Field | Type | Description | -|-------|------|-------------| -| `id` | string | Unique entry ID | -| `event_type` | string | `delegation`, `decision`, `gate`, or `hitl` | -| `actor` | string | Workspace ID that generated the event | -| `summary` | string | Human-readable event description | -| `chain_valid` | bool | `false` if the entry's hash does not match the prior chain — indicates possible tampering | -| `created_at` | string (ISO 8601) | Event timestamp | -| `cursor` | string \| null | Opaque pagination cursor; `null` when there are no more entries | - -Example response: - -```json -{ - "entries": [ - { - "id": "aud_xyz789", - "event_type": "delegation", - "actor": "ws_abc123", - "summary": "Delegated task 'fix CI' to Backend Engineer", - "chain_valid": true, - "created_at": "2026-04-17T14:05:00Z" - } - ], - "cursor": "eyJpZCI6ImF1ZF94eXo3ODkifQ" -} -``` - -### Session Search +## Session Search | Method | Path | Auth | Description | |--------|------|------|-------------| @@ -462,22 +429,11 @@ Bearer token management for workspaces. | POST | `/workspaces/:id/tokens` | WorkspaceAuth | Create a new bearer token for the workspace. | | DELETE | `/workspaces/:id/tokens/:tokenId` | WorkspaceAuth | Revoke a specific token. | -### Test Token (Development Only) +### Admin token minting | Method | Path | Auth | Description | |--------|------|------|-------------| -| GET | `/admin/workspaces/:id/test-token` | None | Mint a fresh bearer token for E2E scripts. Returns 404 unless `MOLECULE_ENV != production` or `MOLECULE_ENABLE_TEST_TOKENS=1`. | - ---- - -## Teams - -Expand and collapse team views in the Canvas hierarchy. - -| Method | Path | Auth | Description | -|--------|------|------|-------------| -| POST | `/workspaces/:id/expand` | WorkspaceAuth | Expand a team workspace to show its children on the canvas. | -| POST | `/workspaces/:id/collapse` | WorkspaceAuth | Collapse a team workspace to hide its children. | +| POST | `/admin/workspaces/:id/tokens` | AdminAuth | Mint a fresh bearer token for a workspace (admin / bootstrap / E2E use). The earlier unauthenticated `GET /admin/workspaces/:id/test-token` route was removed; minting now requires AdminAuth. | --- -- 2.52.0