mirror of
https://github.com/tiennm99/goclaw.git
synced 2026-10-14 14:17:40 +00:00
docs: consolidate HTTP API into single v3-only reference
Merge docs/22-v3-http-endpoints.md into docs/18-http-api.md, adding episodic memory, evolution metrics, vault, orchestration, and v3 flags sections. Drop File Reference table in favour of 4-row module table. Add missing live routes (TTS, backup/restore, CLI agent grants, cancel- summon, system-prompt-preview, vault full CRUD, github-releases, shell-deny-groups). Delete docs/22-v3-http-endpoints.md and update cross-references in doc 21.
This commit is contained in:
viettranx committed
1 parent
985de60d93
commit
d7e2883926
3 files changed
+465
-708
No files matched your search
+463
-141
@@ -11,7 +11,7 @@ Interactive documentation is available at `/docs` (Swagger UI) and the raw OpenA
|
||||
All HTTP endpoints (except `/health`) require authentication via Bearer token in the `Authorization` header:
|
||||
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
Authorization: Bearer <TOKEN>
|
||||
```
|
||||
|
||||
Two token types are accepted:
|
||||
@@ -23,7 +23,7 @@ Two token types are accepted:
|
||||
|
||||
API keys are hashed with SHA-256 before lookup — the raw key is never stored. See [20 — API Keys & Auth](20-api-keys-auth.md) for details.
|
||||
|
||||
> Some endpoints accept the token as a query parameter `?token=<token>` for use in `<img>` and `<audio>` tags (e.g., `/v1/files/`, `/v1/media/`).
|
||||
> Some endpoints accept the token as a query parameter `?token=<TOKEN>` for use in `<img>` and `<audio>` tags (e.g., `/v1/files/`, `/v1/media/`).
|
||||
|
||||
### Common Headers
|
||||
|
||||
@@ -95,6 +95,7 @@ CRUD operations for agent management. Requires `X-GoClaw-User-Id` header for mul
|
||||
| `GET` | `/v1/agents/{id}` | Get agent by ID or key | Bearer |
|
||||
| `PUT` | `/v1/agents/{id}` | Update agent (owner only) | Bearer |
|
||||
| `DELETE` | `/v1/agents/{id}` | Delete agent (owner only) | Bearer |
|
||||
| `POST` | `/v1/agents/sync-workspace` | Sync agent workspace files | Admin |
|
||||
|
||||
### Shares
|
||||
|
||||
@@ -110,6 +111,8 @@ CRUD operations for agent management. Requires `X-GoClaw-User-Id` header for mul
|
||||
|--------|------|-------------|
|
||||
| `POST` | `/v1/agents/{id}/regenerate` | Regenerate agent config with custom prompt |
|
||||
| `POST` | `/v1/agents/{id}/resummon` | Retry initial LLM summoning |
|
||||
| `POST` | `/v1/agents/{id}/cancel-summon` | Cancel an in-progress summon |
|
||||
| `GET` | `/v1/agents/{id}/system-prompt-preview` | Preview rendered system prompt |
|
||||
|
||||
### Predefined Agent Instances
|
||||
|
||||
@@ -117,7 +120,6 @@ CRUD operations for agent management. Requires `X-GoClaw-User-Id` header for mul
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/v1/agents/{id}/instances` | List user instances |
|
||||
| `GET` | `/v1/agents/{id}/instances/{userID}/files` | List user context files |
|
||||
| `GET` | `/v1/agents/{id}/instances/{userID}/files/{fileName}` | Get specific user context file |
|
||||
| `PUT` | `/v1/agents/{id}/instances/{userID}/files/{fileName}` | Update user file (USER.md only) |
|
||||
| `PATCH` | `/v1/agents/{id}/instances/{userID}/metadata` | Update instance metadata |
|
||||
|
||||
@@ -466,6 +468,7 @@ Per-user credential storage for MCP servers (e.g., API keys users provide for ex
|
||||
| `GET` | `/v1/tools/builtin` | List all built-in tools |
|
||||
| `GET` | `/v1/tools/builtin/{name}` | Get tool definition |
|
||||
| `PUT` | `/v1/tools/builtin/{name}` | Update enabled/settings |
|
||||
| `GET` | `/v1/tools/builtin/{name}/tenant-config` | Get tenant-level tool config |
|
||||
| `PUT` | `/v1/tools/builtin/{name}/tenant-config` | Set tenant-level tool config |
|
||||
| `DELETE` | `/v1/tools/builtin/{name}/tenant-config` | Delete tenant-level tool config |
|
||||
|
||||
@@ -492,6 +495,26 @@ Set `"dryRun": true` to return tool schema without execution.
|
||||
|
||||
---
|
||||
|
||||
## 9. TTS
|
||||
|
||||
Text-to-speech synthesis and configuration.
|
||||
|
||||
### Synthesis & Connection
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `POST` | `/v1/tts/synthesize` | Synthesize speech from text (operator role) |
|
||||
| `POST` | `/v1/tts/test-connection` | Test TTS provider connection (operator role) |
|
||||
|
||||
### Configuration
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/v1/tts/config` | Get tenant TTS configuration (admin) |
|
||||
| `POST` | `/v1/tts/config` | Save tenant TTS configuration (admin) |
|
||||
|
||||
---
|
||||
|
||||
## 10. Memory
|
||||
|
||||
Per-agent vector memory using pgvector.
|
||||
@@ -512,7 +535,80 @@ Optional query parameter `?user_id=` for per-user scoping.
|
||||
|
||||
---
|
||||
|
||||
## 11. Knowledge Graph
|
||||
## 11. Episodic Memory
|
||||
|
||||
Episodic memory captures conversation summaries per user session for long-term context continuity.
|
||||
|
||||
### List Episodic Summaries
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/episodic
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `user_id` | string | Filter by user ID (optional). |
|
||||
| `limit` | integer | Max results (default: 20, max: 500). |
|
||||
| `offset` | integer | Pagination offset (default: 0). |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"user_id": "user-123",
|
||||
"summary": "User asked about deployment pipeline optimization. Discussed GitHub Actions, Docker layers, caching strategies. User implemented multi-stage builds.",
|
||||
"key_entities": ["GitHub Actions", "Docker", "CI/CD"],
|
||||
"sentiment": "positive",
|
||||
"interaction_count": 5,
|
||||
"tokens_exchanged": 4200,
|
||||
"created_at": "2026-04-05T10:00:00Z",
|
||||
"updated_at": "2026-04-05T11:30:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Search Episodic Summaries
|
||||
|
||||
```
|
||||
POST /v1/agents/{agentID}/episodic/search
|
||||
```
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "Docker optimization strategies",
|
||||
"user_id": "optional-user-id",
|
||||
"max_results": 10,
|
||||
"min_score": 0.5
|
||||
}
|
||||
```
|
||||
|
||||
Runs hybrid search combining BM25 (keyword) and vector (semantic) matching.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"user_id": "user-123",
|
||||
"summary": "User asked about deployment pipeline optimization...",
|
||||
"similarity_score": 0.92,
|
||||
"created_at": "2026-04-05T10:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Knowledge Graph
|
||||
|
||||
Per-agent entity-relation graph.
|
||||
|
||||
@@ -526,6 +622,7 @@ Per-agent entity-relation graph.
|
||||
| `POST` | `/v1/agents/{agentID}/kg/extract` | LLM-powered entity extraction |
|
||||
| `GET` | `/v1/agents/{agentID}/kg/stats` | Knowledge graph statistics |
|
||||
| `GET` | `/v1/agents/{agentID}/kg/graph` | Full graph for visualization |
|
||||
| `GET` | `/v1/agents/{agentID}/kg/graph/compact` | Compact graph optimized for 10k+ nodes |
|
||||
| `POST` | `/v1/agents/{agentID}/kg/dedup/scan` | Scan for duplicate entities |
|
||||
| `GET` | `/v1/agents/{agentID}/kg/dedup` | List dedup candidates |
|
||||
| `POST` | `/v1/agents/{agentID}/kg/merge` | Merge duplicate entities |
|
||||
@@ -533,7 +630,282 @@ Per-agent entity-relation graph.
|
||||
|
||||
---
|
||||
|
||||
## 12. Channels
|
||||
## 13. Knowledge Vault
|
||||
|
||||
Persistent knowledge vault stores documents with vector embeddings and outbound/backlink graph connections.
|
||||
|
||||
### Global Vault Operations
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/v1/vault/documents` | List all vault documents (cross-agent) |
|
||||
| `POST` | `/v1/vault/documents` | Create vault document |
|
||||
| `GET` | `/v1/vault/documents/{docID}` | Get document |
|
||||
| `PUT` | `/v1/vault/documents/{docID}` | Update document |
|
||||
| `DELETE` | `/v1/vault/documents/{docID}` | Delete document |
|
||||
| `GET` | `/v1/vault/documents/{docID}/links` | Get document outlinks and backlinks |
|
||||
| `POST` | `/v1/vault/links` | Create link between documents |
|
||||
| `DELETE` | `/v1/vault/links/{linkID}` | Delete link |
|
||||
| `POST` | `/v1/vault/links/batch` | Batch get links |
|
||||
| `POST` | `/v1/vault/upload` | Upload document file |
|
||||
| `POST` | `/v1/vault/rescan` | Rescan vault for FS sync |
|
||||
| `GET` | `/v1/vault/tree` | Get vault file tree |
|
||||
| `POST` | `/v1/vault/search` | Hybrid FTS+vector search (cross-agent) |
|
||||
| `GET` | `/v1/vault/enrichment/status` | Get enrichment pipeline status |
|
||||
| `POST` | `/v1/vault/enrichment/stop` | Stop enrichment pipeline |
|
||||
| `GET` | `/v1/vault/graph` | Get vault document relationship graph |
|
||||
|
||||
### Per-Agent Vault Operations
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/v1/agents/{agentID}/vault/documents` | List agent vault documents |
|
||||
| `GET` | `/v1/agents/{agentID}/vault/documents/{docID}` | Get agent document |
|
||||
| `POST` | `/v1/agents/{agentID}/vault/documents` | Create agent document |
|
||||
| `PUT` | `/v1/agents/{agentID}/vault/documents/{docID}` | Update agent document |
|
||||
| `DELETE` | `/v1/agents/{agentID}/vault/documents/{docID}` | Delete agent document |
|
||||
| `GET` | `/v1/agents/{agentID}/vault/documents/{docID}/links` | Get agent document links |
|
||||
| `POST` | `/v1/agents/{agentID}/vault/search` | Search agent vault documents |
|
||||
| `POST` | `/v1/agents/{agentID}/vault/links` | Create link for agent document |
|
||||
| `DELETE` | `/v1/agents/{agentID}/vault/links/{linkID}` | Delete agent document link |
|
||||
|
||||
**Query Parameters (list):**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `scope` | string | Filter by scope (e.g., `team`, `user`, `global`). |
|
||||
| `doc_type` | string | Comma-separated doc types (e.g., `guide,reference,note`). |
|
||||
| `limit` | integer | Max results (default: 20, max: 500). |
|
||||
| `offset` | integer | Pagination offset. |
|
||||
| `agent_id` | string | (Cross-agent only) Filter by specific agent. |
|
||||
|
||||
---
|
||||
|
||||
## 14. Evolution Metrics & Suggestions
|
||||
|
||||
Per-agent evolution metrics track tool usage, retrieval performance, and user feedback to drive automated agent improvements.
|
||||
|
||||
### Get Evolution Metrics
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/evolution/metrics
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `type` | string | no | Filter by metric type: `tool`, `retrieval`, `feedback`. Omit for all types. |
|
||||
| `aggregate` | boolean | no | Return aggregated metrics (grouped by tool/metric). Default: `false` (raw metrics). |
|
||||
| `since` | ISO 8601 | no | Start timestamp (default: 7 days ago). Example: `2026-04-01T00:00:00Z` |
|
||||
| `limit` | integer | no | Max results (default: 100, max: 500). |
|
||||
|
||||
**Response (raw metrics):**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"metric_type": "tool",
|
||||
"tool_name": "web_fetch",
|
||||
"metric_key": "invocation_count",
|
||||
"metric_value": 15,
|
||||
"metadata": {"status": "success"},
|
||||
"recorded_at": "2026-04-06T10:30:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Response (aggregated metrics):**
|
||||
|
||||
```json
|
||||
{
|
||||
"tool_aggregates": [
|
||||
{
|
||||
"tool_name": "web_fetch",
|
||||
"invocation_count": 15,
|
||||
"success_count": 14,
|
||||
"failure_count": 1,
|
||||
"avg_duration_ms": 2340
|
||||
}
|
||||
],
|
||||
"retrieval_aggregates": [
|
||||
{
|
||||
"query_count": 42,
|
||||
"avg_recall": 0.78,
|
||||
"avg_precision": 0.85,
|
||||
"avg_relevance_score": 0.81
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### List Evolution Suggestions
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/evolution/suggestions
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `status` | string | Filter: `pending`, `approved`, `applied`, `rejected`, `rolled_back`. Omit for all. |
|
||||
| `limit` | integer | Max results (default: 50, max: 500). |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"suggestion_type": "low_retrieval_usage",
|
||||
"status": "pending",
|
||||
"title": "Improve retrieval threshold",
|
||||
"description": "Recent queries show low recall. Consider lowering retrieval_threshold from 0.5 to 0.4.",
|
||||
"parameters": {
|
||||
"current_threshold": 0.5,
|
||||
"proposed_threshold": 0.4,
|
||||
"confidence": 0.85
|
||||
},
|
||||
"created_at": "2026-04-06T09:00:00Z",
|
||||
"reviewed_by": null,
|
||||
"reviewed_at": null
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Suggestion Types:**
|
||||
- `low_retrieval_usage` — Retrieval recall is below threshold for recent queries.
|
||||
- `tool_failure` — High failure rate detected for a tool.
|
||||
- `repeated_tool` — Tool called repeatedly without context change; candidate for skill.
|
||||
|
||||
### Update Suggestion Status
|
||||
|
||||
```
|
||||
PATCH /v1/agents/{agentID}/evolution/suggestions/{suggestionID}
|
||||
```
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "approved",
|
||||
"reviewed_by": "optional-user-id"
|
||||
}
|
||||
```
|
||||
|
||||
**Valid status transitions:** `pending` → `approved`, `rejected`, `rolled_back`.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 15. Orchestration Mode
|
||||
|
||||
Determines how an agent routes requests (standalone, delegation, team-based).
|
||||
|
||||
### Get Agent Orchestration Mode
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/orchestration
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "delegate",
|
||||
"delegate_targets": [
|
||||
{
|
||||
"agent_key": "research-agent",
|
||||
"display_name": "Research Specialist"
|
||||
}
|
||||
],
|
||||
"team": null
|
||||
}
|
||||
```
|
||||
|
||||
Or in team mode:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "team",
|
||||
"delegate_targets": [],
|
||||
"team": {
|
||||
"id": "uuid",
|
||||
"name": "Platform Team"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Mode values:**
|
||||
- `standalone` — No delegation. Agent handles all requests directly.
|
||||
- `delegate` — Routes complex requests to specialized agents (via agent links).
|
||||
- `team` — Routes to team members via task system.
|
||||
|
||||
---
|
||||
|
||||
## 16. V3 Feature Flags
|
||||
|
||||
Per-agent feature flags control v3 system capabilities (evolution, episodic memory, vault, etc.).
|
||||
|
||||
### Get V3 Flags
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/v3-flags
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"evolution_enabled": true,
|
||||
"episodic_enabled": true,
|
||||
"vault_enabled": true,
|
||||
"orchestration_enabled": false,
|
||||
"skill_evolve": true,
|
||||
"self_evolve": false
|
||||
}
|
||||
```
|
||||
|
||||
### Update V3 Flags
|
||||
|
||||
```
|
||||
PATCH /v1/agents/{agentID}/v3-flags
|
||||
```
|
||||
|
||||
Accepts partial updates. Flag keys are validated against recognized v3 flags.
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"evolution_enabled": true,
|
||||
"episodic_enabled": false,
|
||||
"vault_enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 17. Channels
|
||||
|
||||
### Channel Instances
|
||||
|
||||
@@ -577,7 +949,7 @@ Credentials are masked in HTTP responses.
|
||||
|
||||
---
|
||||
|
||||
## 13. Pending Messages
|
||||
## 18. Pending Messages
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
@@ -590,7 +962,7 @@ Compaction runs in the background. Falls back to hard delete if no LLM provider
|
||||
|
||||
---
|
||||
|
||||
## 14. Team Events
|
||||
## 19. Team Events
|
||||
|
||||
Team activity and audit trail.
|
||||
|
||||
@@ -600,7 +972,7 @@ Team activity and audit trail.
|
||||
|
||||
---
|
||||
|
||||
## 16. Secure CLI Credentials
|
||||
## 20. Secure CLI Credentials
|
||||
|
||||
CLI authentication credentials for secure command execution. Requires **admin role** (full gateway token or empty gateway token in dev/single-user mode).
|
||||
|
||||
@@ -608,10 +980,11 @@ CLI authentication credentials for secure command execution. Requires **admin ro
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/v1/cli-credentials` | List all credentials |
|
||||
| `POST` | `/v1/cli-credentials` | Create new credential |
|
||||
| `GET` | `/v1/cli-credentials/presets` | Get preset credential templates |
|
||||
| `POST` | `/v1/cli-credentials/check-binary` | Check binary availability |
|
||||
| `GET` | `/v1/cli-credentials/{id}` | Get credential details |
|
||||
| `PUT` | `/v1/cli-credentials/{id}` | Update credential |
|
||||
| `DELETE` | `/v1/cli-credentials/{id}` | Delete credential |
|
||||
| `GET` | `/v1/cli-credentials/presets` | Get preset credential templates |
|
||||
| `POST` | `/v1/cli-credentials/{id}/test` | Test credential connection (dry-run) |
|
||||
|
||||
### Per-User Credentials
|
||||
@@ -623,9 +996,19 @@ CLI authentication credentials for secure command execution. Requires **admin ro
|
||||
| `PUT` | `/v1/cli-credentials/{id}/user-credentials/{userId}` | Set user credential |
|
||||
| `DELETE` | `/v1/cli-credentials/{id}/user-credentials/{userId}` | Delete user credential |
|
||||
|
||||
### Agent Grants
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/v1/cli-credentials/{id}/agent-grants` | List agent grants for CLI cred |
|
||||
| `POST` | `/v1/cli-credentials/{id}/agent-grants` | Create agent grant |
|
||||
| `GET` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` | Get agent grant |
|
||||
| `PUT` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` | Update agent grant |
|
||||
| `DELETE` | `/v1/cli-credentials/{id}/agent-grants/{grantId}` | Delete agent grant |
|
||||
|
||||
---
|
||||
|
||||
## 17. Runtime & Packages Management
|
||||
## 21. Runtime & Packages Management
|
||||
|
||||
Manage system (apk), Python (pip), and Node (npm) package installation in the GoClaw runtime container. These endpoints do not inspect host-level runtimes. Requires authentication. When `GOCLAW_GATEWAY_TOKEN` is empty (dev/single-user mode), all users get admin role and can manage packages.
|
||||
|
||||
@@ -697,15 +1080,6 @@ POST /v1/packages/uninstall
|
||||
|
||||
Same format as install. System packages are removed from persist file and container state.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"error": ""
|
||||
}
|
||||
```
|
||||
|
||||
### Check Runtime Availability
|
||||
|
||||
```
|
||||
@@ -729,11 +1103,25 @@ Check which prerequisite runtimes are available inside the active GoClaw runtime
|
||||
}
|
||||
```
|
||||
|
||||
The published `ghcr.io/nextlevelbuilder/goclaw:latest` image is the minimal variant, so missing Python or Node runtimes can be expected there.
|
||||
### GitHub Releases
|
||||
|
||||
```
|
||||
GET /v1/packages/github-releases
|
||||
```
|
||||
|
||||
Lists available GoClaw GitHub release versions for the update checker.
|
||||
|
||||
### Shell Deny Groups
|
||||
|
||||
```
|
||||
GET /v1/shell-deny-groups
|
||||
```
|
||||
|
||||
List shell command deny group patterns configured for the gateway.
|
||||
|
||||
---
|
||||
|
||||
## 18. Traces & Costs
|
||||
## 22. Traces & Costs
|
||||
|
||||
LLM call tracing and cost analysis.
|
||||
|
||||
@@ -755,7 +1143,7 @@ LLM call tracing and cost analysis.
|
||||
|
||||
---
|
||||
|
||||
## 19. Usage & Analytics
|
||||
## 23. Usage & Analytics
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
@@ -769,7 +1157,7 @@ LLM call tracing and cost analysis.
|
||||
|
||||
---
|
||||
|
||||
## 20. Activity & Audit
|
||||
## 24. Activity & Audit
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
@@ -777,7 +1165,7 @@ LLM call tracing and cost analysis.
|
||||
|
||||
---
|
||||
|
||||
## 21. Storage
|
||||
## 25. Storage
|
||||
|
||||
Workspace file management.
|
||||
|
||||
@@ -798,7 +1186,7 @@ Workspace file management.
|
||||
|
||||
---
|
||||
|
||||
## 22. Voices & Audio
|
||||
## 26. Voices & Audio
|
||||
|
||||
Voice discovery for TTS providers (ElevenLabs). All endpoints are tenant-scoped and require tenant admin or operator role.
|
||||
|
||||
@@ -809,11 +1197,6 @@ Voice discovery for TTS providers (ElevenLabs). All endpoints are tenant-scoped
|
||||
|
||||
### `GET /v1/voices`
|
||||
|
||||
Fetch available TTS voices for the current tenant's provider.
|
||||
|
||||
**Query Parameters:**
|
||||
- None
|
||||
|
||||
**Response** (200 OK):
|
||||
```json
|
||||
[
|
||||
@@ -830,24 +1213,12 @@ Fetch available TTS voices for the current tenant's provider.
|
||||
]
|
||||
```
|
||||
|
||||
**Errors:**
|
||||
- 401: Missing or invalid token
|
||||
- 403: Insufficient permissions (requires tenant admin/operator)
|
||||
- 500: Provider error (e.g., ElevenLabs API unreachable)
|
||||
|
||||
**Caching:**
|
||||
- Responses are in-memory cached per tenant with TTL 1h
|
||||
- Cache is shared across all HTTP + WebSocket handlers
|
||||
- Cache miss triggers immediate fetch from provider
|
||||
**Caching:** In-memory cached per tenant with TTL 1h. Cache miss triggers immediate fetch from provider.
|
||||
|
||||
### `POST /v1/voices/refresh`
|
||||
|
||||
Invalidate the voice cache for the current tenant, forcing a fresh fetch on the next request.
|
||||
|
||||
**Admin-only endpoint.** Useful after voice updates or CDN expiry issues.
|
||||
|
||||
**Request body:** (empty)
|
||||
|
||||
**Response** (202 Accepted):
|
||||
```json
|
||||
{ "message": "voice cache invalidated" }
|
||||
@@ -855,7 +1226,7 @@ Invalidate the voice cache for the current tenant, forcing a fresh fetch on the
|
||||
|
||||
---
|
||||
|
||||
## 23. Media
|
||||
## 27. Media
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
@@ -864,7 +1235,7 @@ Invalidate the voice cache for the current tenant, forcing a fresh fetch on the
|
||||
|
||||
---
|
||||
|
||||
## 24. Files
|
||||
## 28. Files
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
@@ -875,7 +1246,7 @@ Auth via Bearer token or `?token=` query param (for `<img>` tags). MIME type aut
|
||||
|
||||
---
|
||||
|
||||
## 25. API Keys
|
||||
## 29. API Keys
|
||||
|
||||
Admin-only endpoints for managing gateway API keys. See [20 — API Keys & Auth](20-api-keys-auth.md) for the full authentication and authorization model.
|
||||
|
||||
@@ -913,7 +1284,7 @@ Admin-only endpoints for managing gateway API keys. See [20 — API Keys & Auth]
|
||||
|
||||
---
|
||||
|
||||
## 26. OAuth
|
||||
## 30. OAuth
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
@@ -948,13 +1319,6 @@ Success payload:
|
||||
"remaining_percent": 76,
|
||||
"reset_after_seconds": 3600,
|
||||
"reset_at": "2026-03-24T20:15:00Z"
|
||||
},
|
||||
{
|
||||
"label": "Secondary",
|
||||
"used_percent": 38,
|
||||
"remaining_percent": 62,
|
||||
"reset_after_seconds": 604800,
|
||||
"reset_at": "2026-03-31T19:15:00Z"
|
||||
}
|
||||
],
|
||||
"core_usage": {
|
||||
@@ -975,32 +1339,15 @@ Success payload:
|
||||
}
|
||||
```
|
||||
|
||||
Failure payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"provider_name": "openai-codex",
|
||||
"success": false,
|
||||
"windows": [],
|
||||
"error": "Quota metadata is missing for this account.",
|
||||
"error_code": "missing_account_id",
|
||||
"action_hint": "Sign in again so GoClaw can restore the ChatGPT account workspace metadata.",
|
||||
"last_updated": "2026-03-24T19:15:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
- Invalid provider slugs return `400`.
|
||||
- Missing provider still returns `404`, and provider type conflicts still return `409`.
|
||||
- Missing quota metadata, expired workspace access, upstream `402`, upstream `403`, and upstream `429` return `200` with a structured failure payload so the dashboard can render actionable state inline.
|
||||
- `needs_reauth`, `is_forbidden`, and `retryable` are boolean hints for UI/state-machine handling.
|
||||
- Missing provider returns `404`, provider type conflicts return `409`.
|
||||
- Missing quota metadata, expired workspace access, upstream `402`/`403`/`429` return `200` with a structured failure payload.
|
||||
- `error_code` can be `missing_account_id`, `reauth_required`, `payment_required`, `quota_api_forbidden`, `quota_endpoint_not_found`, `rate_limited`, `provider_unavailable`, `network_timeout`, `network_error`, `quota_request_failed`, or `unknown_upstream_error`.
|
||||
- Failure payloads still include `windows: []` so clients can treat the envelope consistently.
|
||||
- `core_usage.five_hour` and `core_usage.weekly` are derived from upstream windows. When labels drift, GoClaw falls back to shortest-reset and longest-reset usage windows.
|
||||
|
||||
---
|
||||
|
||||
## 27. Edition
|
||||
## 31. Edition
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
@@ -1008,7 +1355,7 @@ Notes:
|
||||
|
||||
---
|
||||
|
||||
## 28. Tenants
|
||||
## 32. Tenants
|
||||
|
||||
Multi-tenant management (admin only).
|
||||
|
||||
@@ -1024,7 +1371,7 @@ Multi-tenant management (admin only).
|
||||
|
||||
---
|
||||
|
||||
## 29. System Configs
|
||||
## 33. System Configs
|
||||
|
||||
Key-value system configuration store.
|
||||
|
||||
@@ -1037,7 +1384,7 @@ Key-value system configuration store.
|
||||
|
||||
---
|
||||
|
||||
## 30. Team Workspace & Attachments
|
||||
## 34. Team Workspace & Attachments
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
@@ -1047,15 +1394,43 @@ Key-value system configuration store.
|
||||
|
||||
---
|
||||
|
||||
## 31. Shell Deny Groups
|
||||
## 35. Backup & Restore
|
||||
|
||||
System-level backup/restore endpoints (admin only). Stream progress via SSE.
|
||||
|
||||
### System Backup
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/v1/shell-deny-groups` | List shell command deny group patterns |
|
||||
| `POST` | `/v1/system/backup` | Create system backup (streams SSE progress) |
|
||||
| `GET` | `/v1/system/backup/preflight` | Check backup prerequisites |
|
||||
| `GET` | `/v1/system/backup/download/{token}` | Download backup archive |
|
||||
| `POST` | `/v1/system/restore` | Restore from backup archive (streams SSE progress) |
|
||||
|
||||
**Query params for restore:** `skip_db=true`, `skip_files=true`, `dry_run=true`
|
||||
|
||||
### S3 Backup Integration
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `GET` | `/v1/system/backup/s3/config` | Get S3 backup configuration |
|
||||
| `PUT` | `/v1/system/backup/s3/config` | Set S3 backup configuration |
|
||||
| `GET` | `/v1/system/backup/s3/list` | List S3 backup objects |
|
||||
| `POST` | `/v1/system/backup/s3/upload` | Upload backup to S3 |
|
||||
| `POST` | `/v1/system/backup/s3/backup` | Trigger S3 backup |
|
||||
|
||||
### Tenant Backup
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `POST` | `/v1/tenant/backup` | Create tenant-scoped backup |
|
||||
| `GET` | `/v1/tenant/backup/preflight` | Check tenant backup prerequisites |
|
||||
| `GET` | `/v1/tenant/backup/download/{token}` | Download tenant backup archive |
|
||||
| `POST` | `/v1/tenant/restore` | Restore tenant from backup |
|
||||
|
||||
---
|
||||
|
||||
## 32. System
|
||||
## 36. System
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
@@ -1074,7 +1449,7 @@ Key-value system configuration store.
|
||||
|
||||
---
|
||||
|
||||
## 33. MCP Bridge
|
||||
## 37. MCP Bridge
|
||||
|
||||
Exposes GoClaw tools to Claude CLI via streamable HTTP at `/mcp/bridge`. Only listens on localhost. Protected by gateway token with HMAC-signed context headers.
|
||||
|
||||
@@ -1121,69 +1496,16 @@ The following operations are **only available via WebSocket RPC**, not HTTP:
|
||||
- **Cron jobs:** List, create, update, delete, logs (use WebSocket method `cron.*`)
|
||||
- **Send messages:** Send to channels (use WebSocket method `send.*`)
|
||||
- **Config management:** Get, apply, patch (use WebSocket method `config.*`)
|
||||
- **Delegations:** List, get delegation history (use WebSocket method `delegations.*`) — _not currently registered as WS methods either; may be removed_
|
||||
|
||||
These endpoints require an active WebSocket connection to the `/ws` endpoint with proper authentication and agent context.
|
||||
|
||||
---
|
||||
|
||||
## Notes on V3 Endpoints
|
||||
## Module Reference
|
||||
|
||||
GoClaw v3 introduces new HTTP endpoints for agent evolution metrics, episodic memory, knowledge vault, and orchestration. These are documented separately in [22 — V3 HTTP Endpoints](22-v3-http-endpoints.md) to keep this document focused on the core REST API. V3 endpoints follow the same authentication, error handling, and header conventions as documented above.
|
||||
|
||||
---
|
||||
|
||||
## File Reference
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `internal/http/chat_completions.go` | OpenAI-compatible chat API |
|
||||
| `internal/http/responses.go` | OpenResponses protocol |
|
||||
| `internal/http/agents.go` | Agent CRUD + shares + instances + files |
|
||||
| `internal/http/skills.go` | Skill management + grants + versions |
|
||||
| `internal/http/providers.go` | Provider CRUD + verification + models |
|
||||
| `internal/http/mcp.go` | MCP server management + grants + requests |
|
||||
| `internal/http/builtin_tools.go` | Built-in tool management |
|
||||
| `internal/http/tools_invoke.go` | Direct tool invocation |
|
||||
| `internal/http/channel_instances.go` | Channel instance management + contacts |
|
||||
| `internal/http/memory_handlers.go` | Memory document management + search + indexing |
|
||||
| `internal/http/knowledge_graph.go` | Knowledge graph API (entities, relations, traversal) |
|
||||
| `internal/http/traces.go` | LLM trace listing + export |
|
||||
| `internal/http/usage.go` | Usage analytics + costs |
|
||||
| `internal/http/activity.go` | Activity audit log |
|
||||
| `internal/http/storage.go` | Workspace file management + size calculation |
|
||||
| `internal/http/media_upload.go` | Media file upload |
|
||||
| `internal/http/media_serve.go` | Media file serving |
|
||||
| `internal/http/files.go` | Workspace file serving |
|
||||
| `internal/http/api_keys.go` | API key management + revoke |
|
||||
| `internal/http/team_events.go` | Team event history API |
|
||||
| `internal/http/team_attachments.go` | Team attachment downloads |
|
||||
| `internal/http/workspace_upload.go` | Team workspace upload + move |
|
||||
| `internal/http/secure_cli.go` | CLI credential management |
|
||||
| `internal/http/packages.go` | Runtime package management (apk/pip/npm) |
|
||||
| `internal/http/pending_messages.go` | Pending message groups + compaction |
|
||||
| `internal/http/oauth.go` | OAuth authentication flows |
|
||||
| `internal/http/openapi.go` | OpenAPI spec + Swagger UI |
|
||||
| `internal/http/auth.go` | Authentication helpers |
|
||||
| `internal/gateway/server.go` | HTTP mux and route wiring |
|
||||
| `cmd/gateway.go` | Handler instantiation and wiring |
|
||||
| `cmd/pkg-helper/main.go` | Root-privileged system package helper (apk add/del) |
|
||||
| `internal/skills/package_lister.go` | Query installed packages from apk/pip3/npm |
|
||||
| `internal/http/edition.go` | Edition info endpoint |
|
||||
| `internal/http/system_configs.go` | System config key-value store |
|
||||
| `internal/http/tenants.go` | Multi-tenant management |
|
||||
| `internal/http/mcp_user_credentials.go` | MCP per-user credentials |
|
||||
| `internal/http/mcp_export.go` | MCP export |
|
||||
| `internal/http/mcp_import.go` | MCP import |
|
||||
| `internal/http/skills_export.go` | Skills export |
|
||||
| `internal/http/skills_import.go` | Skills import |
|
||||
| `internal/http/agents_export.go` | Agent export |
|
||||
| `internal/http/agents_import.go` | Agent import |
|
||||
| `internal/http/contact_merge_handlers.go` | Contact merge/unmerge |
|
||||
| `internal/http/user_search.go` | User search |
|
||||
| `internal/http/secure_cli_user_credentials.go` | CLI per-user credentials |
|
||||
| `internal/http/evolution_handlers.go` | V3: Evolution metrics + suggestions endpoints |
|
||||
| `internal/http/episodic_handlers.go` | V3: Episodic memory list + search endpoints |
|
||||
| `internal/http/vault_handlers.go` | V3: Vault document + link endpoints |
|
||||
| `internal/http/orchestration_handlers.go` | V3: Orchestration mode info endpoint |
|
||||
| `internal/http/v3_flags_handlers.go` | V3: Feature flag get/toggle endpoints |
|
||||
| Module | Path | Purpose |
|
||||
|--------|------|---------|
|
||||
| Auth & Routing | `internal/http/`, `internal/gateway/` | Auth middleware, RBAC, request routing, MCP bridge |
|
||||
| Chat, Agents & Skills | `internal/http/chat_completions.go`, `agents*.go`, `skills*.go`, `wake.go` | Conversational endpoints, agent CRUD, skill management |
|
||||
| Memory, Vault & Knowledge | `internal/http/memory.go`, `vault_handlers*.go`, `knowledge_graph.go`, `episodic_handlers.go` | Persistent knowledge, vector memory, document graph |
|
||||
| Evolution, Orchestration & Flags | `internal/http/evolution_handlers.go`, `orchestration_handlers.go`, `v3_flags_handlers.go` | v3 runtime control, metrics, suggestions, feature flags |
|
||||
@@ -637,7 +637,7 @@ Evolution analysis runs as a periodic cron job (default: daily).
|
||||
|
||||
### 8.5 API & WebSocket
|
||||
|
||||
**HTTP Endpoints** (see [22 — V3 HTTP Endpoints](22-v3-http-endpoints.md)):
|
||||
**HTTP Endpoints** (see [18 — HTTP REST API](18-http-api.md#14-evolution-metrics--suggestions)):
|
||||
- `GET /v1/agents/{agentID}/evolution/metrics` — Query/aggregate metrics
|
||||
- `GET /v1/agents/{agentID}/evolution/suggestions` — List suggestions
|
||||
- `PATCH /v1/agents/{agentID}/evolution/suggestions/{suggestionID}` — Approve/reject/rollback
|
||||
@@ -674,4 +674,4 @@ Defaults used if keys absent. Set `evolution_enabled: false` to disable metrics
|
||||
- [15 - Core Skills System](./15-core-skills-system.md) — Bundled system skills, startup seeding, dependency checking
|
||||
- [16 - Skill Publishing System](./16-skill-publishing.md) — `publish_skill` tool and `skill-creator` core skill
|
||||
- [19 - WebSocket RPC Methods](./19-websocket-rpc.md) — V3 WebSocket methods for evolution, episodic, vault
|
||||
- [22 - V3 HTTP Endpoints](./22-v3-http-endpoints.md) — HTTP REST endpoints for evolution metrics, suggestions, episodic memory, vault documents
|
||||
- [18 - HTTP REST API](./18-http-api.md) — HTTP REST endpoints for evolution metrics, suggestions, episodic memory, vault documents
|
||||
@@ -1,565 +0,0 @@
|
||||
# 22 — V3 HTTP Endpoints
|
||||
|
||||
GoClaw v3 introduces new HTTP endpoints for agent evolution, episodic memory, knowledge vault, and orchestration capabilities. All endpoints follow the standard authentication and error response patterns from [18 — HTTP REST API](18-http-api.md).
|
||||
|
||||
---
|
||||
|
||||
## 1. Evolution Metrics & Suggestions
|
||||
|
||||
Per-agent evolution metrics track tool usage, retrieval performance, and user feedback to drive automated agent improvements.
|
||||
|
||||
### Get Evolution Metrics
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/evolution/metrics
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `type` | string | no | Filter by metric type: `tool`, `retrieval`, `feedback`. Omit for all types. |
|
||||
| `aggregate` | boolean | no | Return aggregated metrics (grouped by tool/metric). Default: `false` (raw metrics). |
|
||||
| `since` | ISO 8601 | no | Start timestamp (default: 7 days ago). Example: `2026-04-01T00:00:00Z` |
|
||||
| `limit` | integer | no | Max results (default: 100, max: 500). |
|
||||
|
||||
**Response (raw metrics):**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"metric_type": "tool",
|
||||
"tool_name": "web_fetch",
|
||||
"metric_key": "invocation_count",
|
||||
"metric_value": 15,
|
||||
"metadata": {"status": "success"},
|
||||
"recorded_at": "2026-04-06T10:30:00Z"
|
||||
},
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"metric_type": "retrieval",
|
||||
"metric_key": "recall_rate",
|
||||
"metric_value": 0.78,
|
||||
"metadata": {"query_count": 42},
|
||||
"recorded_at": "2026-04-06T11:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Response (aggregated metrics):**
|
||||
|
||||
```json
|
||||
{
|
||||
"tool_aggregates": [
|
||||
{
|
||||
"tool_name": "web_fetch",
|
||||
"invocation_count": 15,
|
||||
"success_count": 14,
|
||||
"failure_count": 1,
|
||||
"avg_duration_ms": 2340
|
||||
},
|
||||
{
|
||||
"tool_name": "exec",
|
||||
"invocation_count": 8,
|
||||
"success_count": 8,
|
||||
"failure_count": 0,
|
||||
"avg_duration_ms": 1200
|
||||
}
|
||||
],
|
||||
"retrieval_aggregates": [
|
||||
{
|
||||
"query_count": 42,
|
||||
"avg_recall": 0.78,
|
||||
"avg_precision": 0.85,
|
||||
"avg_relevance_score": 0.81
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Status codes:** `200` OK, `400` bad request, `404` agent not found, `500` server error.
|
||||
|
||||
### List Evolution Suggestions
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/evolution/suggestions
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `status` | string | Filter: `pending`, `approved`, `applied`, `rejected`, `rolled_back`. Omit for all. |
|
||||
| `limit` | integer | Max results (default: 50, max: 500). |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"suggestion_type": "low_retrieval_usage",
|
||||
"status": "pending",
|
||||
"title": "Improve retrieval threshold",
|
||||
"description": "Recent queries show low recall. Consider lowering retrieval_threshold from 0.5 to 0.4.",
|
||||
"parameters": {
|
||||
"current_threshold": 0.5,
|
||||
"proposed_threshold": 0.4,
|
||||
"confidence": 0.85
|
||||
},
|
||||
"created_at": "2026-04-06T09:00:00Z",
|
||||
"reviewed_by": null,
|
||||
"reviewed_at": null
|
||||
},
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"suggestion_type": "repeated_tool",
|
||||
"status": "pending",
|
||||
"title": "Tool usage pattern detected",
|
||||
"description": "Tool 'exec' called 5+ times in a row without context change. Consider skill creation.",
|
||||
"parameters": {
|
||||
"tool_name": "exec",
|
||||
"occurrence_count": 12,
|
||||
"pattern_score": 0.92
|
||||
},
|
||||
"created_at": "2026-04-05T14:30:00Z",
|
||||
"reviewed_by": null,
|
||||
"reviewed_at": null
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Suggestion Types:**
|
||||
- `low_retrieval_usage` — Retrieval recall is below threshold for recent queries.
|
||||
- `tool_failure` — High failure rate detected for a tool.
|
||||
- `repeated_tool` — Tool called repeatedly without context change; candidate for skill.
|
||||
|
||||
### Update Suggestion Status
|
||||
|
||||
```
|
||||
PATCH /v1/agents/{agentID}/evolution/suggestions/{suggestionID}
|
||||
```
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "approved",
|
||||
"reviewed_by": "optional-user-id"
|
||||
}
|
||||
```
|
||||
|
||||
**Valid status transitions:** `pending` → `approved`, `rejected`, `rolled_back`.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Episodic Memory Summaries
|
||||
|
||||
Episodic memory captures conversation summaries per user session for long-term context continuity.
|
||||
|
||||
### List Episodic Summaries
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/episodic
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `user_id` | string | Filter by user ID (optional). |
|
||||
| `limit` | integer | Max results (default: 20, max: 500). |
|
||||
| `offset` | integer | Pagination offset (default: 0). |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"user_id": "user-123",
|
||||
"summary": "User asked about deployment pipeline optimization. Discussed GitHub Actions, Docker layers, caching strategies. User implemented multi-stage builds.",
|
||||
"key_entities": ["GitHub Actions", "Docker", "CI/CD"],
|
||||
"sentiment": "positive",
|
||||
"interaction_count": 5,
|
||||
"tokens_exchanged": 4200,
|
||||
"created_at": "2026-04-05T10:00:00Z",
|
||||
"updated_at": "2026-04-05T11:30:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Search Episodic Summaries
|
||||
|
||||
```
|
||||
POST /v1/agents/{agentID}/episodic/search
|
||||
```
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "Docker optimization strategies",
|
||||
"user_id": "optional-user-id",
|
||||
"max_results": 10,
|
||||
"min_score": 0.5
|
||||
}
|
||||
```
|
||||
|
||||
Runs hybrid search combining BM25 (keyword) and vector (semantic) matching.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"user_id": "user-123",
|
||||
"summary": "User asked about deployment pipeline optimization...",
|
||||
"similarity_score": 0.92,
|
||||
"created_at": "2026-04-05T10:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Knowledge Vault
|
||||
|
||||
Persistent knowledge vault stores documents with vector embeddings and outbound/backlink graph connections.
|
||||
|
||||
### List Vault Documents
|
||||
|
||||
Cross-agent listing:
|
||||
```
|
||||
GET /v1/vault/documents
|
||||
```
|
||||
|
||||
Per-agent listing:
|
||||
```
|
||||
GET /v1/agents/{agentID}/vault/documents
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `scope` | string | Filter by scope (e.g., `team`, `user`, `global`). |
|
||||
| `doc_type` | string | Comma-separated doc types (e.g., `guide,reference,note`). |
|
||||
| `limit` | integer | Max results (default: 20, max: 500). |
|
||||
| `offset` | integer | Pagination offset. |
|
||||
| `agent_id` | string | (Cross-agent only) Filter by specific agent. |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"title": "Database Indexing Best Practices",
|
||||
"doc_type": "guide",
|
||||
"scope": "team",
|
||||
"content_preview": "Indexes are crucial for query performance. Types include...",
|
||||
"created_at": "2026-04-01T09:00:00Z",
|
||||
"updated_at": "2026-04-05T14:20:00Z",
|
||||
"outlink_count": 3,
|
||||
"backlink_count": 2
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Get Single Document
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/vault/documents/{docID}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"agent_id": "uuid",
|
||||
"title": "Database Indexing Best Practices",
|
||||
"doc_type": "guide",
|
||||
"scope": "team",
|
||||
"content": "Indexes are crucial for query performance. Types include: B-tree, Hash, Bitmap...",
|
||||
"metadata": {"version": 2, "author": "team-lead"},
|
||||
"created_at": "2026-04-01T09:00:00Z",
|
||||
"updated_at": "2026-04-05T14:20:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Search Vault Documents
|
||||
|
||||
```
|
||||
POST /v1/agents/{agentID}/vault/search
|
||||
```
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "index performance optimization",
|
||||
"scope": "team",
|
||||
"doc_types": ["guide", "reference"],
|
||||
"max_results": 10
|
||||
}
|
||||
```
|
||||
|
||||
Hybrid FTS+vector search combining keyword and semantic matching.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"title": "Database Indexing Best Practices",
|
||||
"doc_type": "guide",
|
||||
"relevance_score": 0.94,
|
||||
"snippet": "...Indexes are crucial for query performance. Types include B-tree, Hash, Bitmap...",
|
||||
"created_at": "2026-04-01T09:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Get Document Links
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/vault/documents/{docID}/links
|
||||
```
|
||||
|
||||
Returns outgoing links and backlinks for a document.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"outlinks": [
|
||||
{
|
||||
"target_doc_id": "uuid",
|
||||
"target_title": "Query Optimization Techniques",
|
||||
"link_type": "references"
|
||||
}
|
||||
],
|
||||
"backlinks": [
|
||||
{
|
||||
"source_doc_id": "uuid",
|
||||
"source_title": "Performance Tuning Guide",
|
||||
"link_type": "referenced_by"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Graph Visualization
|
||||
|
||||
Lightweight endpoints for rendering vault and knowledge graph relationships.
|
||||
|
||||
### Get Vault Graph
|
||||
|
||||
```
|
||||
GET /v1/vault/graph
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `agent_id` | string | Filter by agent (optional). |
|
||||
| `team_id` | string | Scope by team (optional). |
|
||||
| `limit` | integer | Max nodes to return (default: 500, max: 2000). |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"label": "Document Title",
|
||||
"type": "document",
|
||||
"agent_id": "uuid",
|
||||
"metadata": {}
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{
|
||||
"id": "link-uuid",
|
||||
"source": "doc-uuid-1",
|
||||
"target": "doc-uuid-2",
|
||||
"type": "wikilink"
|
||||
}
|
||||
],
|
||||
"total_nodes": 150,
|
||||
"total_edges": 120
|
||||
}
|
||||
```
|
||||
|
||||
Used for vault document relationship visualization with FA2 layout (web worker rendering).
|
||||
|
||||
### Get Knowledge Graph (Compact)
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/kg/graph/compact
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `limit` | integer | Max nodes (default: 500, max: 2000). Optimized 10k node load. |
|
||||
|
||||
**Response:** Same format as vault graph; nodes represent semantic entities, edges represent relationship types.
|
||||
|
||||
**Features:**
|
||||
- Semantic zoom support
|
||||
- Optimized for 10k+ entity graphs
|
||||
- FA2 layout computed via web worker
|
||||
|
||||
---
|
||||
|
||||
## 5. Orchestration Mode
|
||||
|
||||
Determines how an agent routes requests (standalone, delegation, team-based).
|
||||
|
||||
### Get Agent Orchestration Mode
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/orchestration
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "delegate",
|
||||
"delegate_targets": [
|
||||
{
|
||||
"agent_key": "research-agent",
|
||||
"display_name": "Research Specialist"
|
||||
},
|
||||
{
|
||||
"agent_key": "doc-agent",
|
||||
"display_name": "Documentation Expert"
|
||||
}
|
||||
],
|
||||
"team": null
|
||||
}
|
||||
```
|
||||
|
||||
Or in team mode:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "team",
|
||||
"delegate_targets": [],
|
||||
"team": {
|
||||
"id": "uuid",
|
||||
"name": "Platform Team"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Mode values:**
|
||||
- `standalone` — No delegation. Agent handles all requests directly.
|
||||
- `delegate` — Routes complex requests to specialized agents (via agent links).
|
||||
- `team` — Routes to team members via task system.
|
||||
|
||||
---
|
||||
|
||||
## 6. V3 Feature Flags
|
||||
|
||||
Per-agent feature flags control v3 system capabilities (evolution, episodic memory, vault, etc.).
|
||||
|
||||
### Get V3 Flags
|
||||
|
||||
```
|
||||
GET /v1/agents/{agentID}/v3-flags
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"evolution_enabled": true,
|
||||
"episodic_enabled": true,
|
||||
"vault_enabled": true,
|
||||
"orchestration_enabled": false,
|
||||
"skill_evolve": true,
|
||||
"self_evolve": false
|
||||
}
|
||||
```
|
||||
|
||||
### Update V3 Flags
|
||||
|
||||
```
|
||||
PATCH /v1/agents/{agentID}/v3-flags
|
||||
```
|
||||
|
||||
Accepts partial updates. Flag keys are validated against recognized v3 flags.
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{
|
||||
"evolution_enabled": true,
|
||||
"episodic_enabled": false,
|
||||
"vault_enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Reference
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `internal/http/evolution_handlers.go` | Metrics + suggestions endpoints |
|
||||
| `internal/http/episodic_handlers.go` | Episodic memory list + search endpoints |
|
||||
| `internal/http/vault_handlers.go` | Knowledge vault document + link endpoints |
|
||||
| `internal/http/vault_graph_handler.go` | Vault + KG graph visualization endpoints |
|
||||
| `internal/http/orchestration_handlers.go` | Orchestration mode info endpoint |
|
||||
| `internal/http/v3_flags_handlers.go` | V3 feature flag get/toggle endpoints |
|
||||
| `internal/store/evolution_store.go` | Evolution metrics/suggestions store interface |
|
||||
| `internal/store/episodic_store.go` | Episodic memory store interface |
|
||||
| `internal/store/vault_store.go` | Knowledge vault store interface |
|
||||
| `internal/store/pg/evolution_metrics.go` | PostgreSQL evolution metrics impl |
|
||||
| `internal/store/pg/evolution_suggestions.go` | PostgreSQL evolution suggestions impl |
|
||||
| `internal/store/pg/episodic.go` | PostgreSQL episodic memory impl |
|
||||
| `internal/store/pg/vault.go` | PostgreSQL vault documents/links impl |
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- [18 — HTTP REST API](18-http-api.md) — Standard authentication, error responses, common headers
|
||||
- [19 — WebSocket RPC Methods](19-websocket-rpc.md) — V3 WebSocket methods (evolution, orchestration)
|
||||
- [21 — Agent Evolution & Skill Management](21-agent-evolution-and-skill-management.md) — Evolution system architecture and suggestion engine
|
||||
Reference in new issue
Block a user