docs(api-reference): accuracy pass vs real router + dedup Audit Ledger #68

Merged
documentation-specialist merged 1 commits from docs/api-reference-accuracy into main 2026-06-02 15:05:49 +00:00
+10 -54
View File
@@ -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=<cursor>`, and `?limit=<n>` (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. |
---