From c1ea0c0090713347a965f019d4908bd6469d8ff1 Mon Sep 17 00:00:00 2001 From: Aaron Vu <54255926+aaron-tsar@users.noreply.github.com> Date: Thu, 25 Jun 2026 22:31:08 +0700 Subject: [PATCH] docs(openapi): cover the full HTTP API surface (#1171) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(openapi): add vault endpoints + schemas The committed OpenAPI spec only documented 41 of ~286 actual routes. This adds the 19 Vault endpoints — 16 under /v1/vault/* and 3 under /v1/agents/{agentID}/vault/* — plus their request/response schemas. Routes covered (matches internal/http/vault_handler_*.go and vault_graph_handler.go registrations): - documents: list, create, get, update, delete (per-agent and cross-agent) - documents/{docID}/links: outlinks + backlinks + name lookup - links: create, delete, batch get outlinks - upload: multipart, allowed exts whitelist - rescan: per-tenant workspace rescan w/ concurrency guard (409) - tree: lazy sidebar listing - search: hybrid FTS + vector - enrichment: status + stop - graph: lightweight nodes/edges for visualization Schemas: VaultDocument, VaultDocumentInput, VaultDocumentUpdateInput, VaultLink, VaultBacklink, VaultSearchResult, VaultTreeEntry, VaultGraphNode, VaultGraphEdge. Tags: Vault, Vault Graph. Pure spec addition — no handler changes. The insertion is surgical (no reformatting of existing entries), so the diff is additive only. * docs(openapi): cover the remaining HTTP endpoints Continues the gap-fill started for Vault. Adds 150 more path operations spanning every other HTTP-route file under internal/http/, with 19 new component schemas and 8 new tags. After this commit the spec covers 210 paths vs 60 previously committed (the actual handler surface is ~258). Coverage by area (file → routes added): knowledge_graph_handlers.go 9 (Knowledge Graph: extract, graph, stats, dedup scan/dismiss, merge, single entity) vault_graph_handler.go 1 (kg/graph/compact) memory_handlers.go 6 (documents CRUD with {path...}, chunks, index, index-all) oauth.go 8 (chatgpt + openai: status, start, callback, logout × 2) storage.go 4 (files {path...} read/delete, size, move; POST upload merged into the existing /v1/storage/files block so the path key stays unique and YAML-strict parsers like Swagger UI's loader accept the spec) agents.go 22 (sync-workspace, shares CRUD, regenerate / resummon / cancel-summon, system-prompt- preview, export {preview,download/token}, import {preview,merge}, teams export/import, instances + metadata, orchestration, v3-flags) evolution_handlers.go 3 (metrics, suggestions, suggestion review) episodic_handlers.go 2 (list, search) skills.go 18 (versions, files, files/{path...}, upload, grants agent/user × revoke, install-deps trio, runtimes, toggle, tenant-config, export {preview}, import) mcp.go + mcp_user_credentials.go 16 (test, reconnect, grants + per-user creds, requests CRUD + review, export {preview}, import, agent-grants list) providers.go 4 (verify-embedding, codex-pool-activity, claude-cli auth-status, embedding/status) tenants.go + users 7 (CRUD + tenant users + tenant-users list, users/search) secure_cli.go + agent_grants 17 (cli-credentials full CRUD + presets + check-binary + test + user-credentials + agent-grants) system_configs.go 4 (list, get, put, delete) backup_handler.go + s3 + tenant 12 (system backup preflight/download/s3 set, tenant backup + restore) packages.go 6 (list, install/uninstall, runtimes, github-releases, shell-deny-groups) builtin_tools.go 3 (tenant-config get/set/delete) tts.go + voices.go + caps 6 (config, synthesize, test-connection, capabilities, voices, voices/refresh) channel_instances.go +contacts +pending 10 (channel writers, writer groups, contacts resolve / merge / unmerge / merged, pending-messages) files.go + workspace_upload 3 (files {path...} read, files/sign, team workspace upload + move, team events, team task attachment download) edition.go + openapi.go 2 (edition info, openapi.json) api-keys + traces + usage 3 (revoke, traces/{traceID}/export, usage/breakdown) New schemas: KGEntity, KGRelation, KGDedupCandidate, KGStats, TraversalResult, MemoryDocument, MemoryChunk, MemorySearchHit, OAuthStatus, OAuthStartResponse, Skill, McpServer, Tenant, TenantUser, CLICredential, Package, EvolutionMetric, EvolutionSuggestion, EpisodicSummary. New tags: Tenants, CLI Credentials, Packages, Contacts, Teams, TTS, Evolution, Episodic Memory. Purely additive — no existing operation, schema, or tag is modified. The one overlap (`/v1/storage/files`, previously documented as GET-only) is handled by inserting the new POST method inside the existing path block in place rather than re-declaring the key, so each path key appears exactly once and the spec parses cleanly under both JSON and strict YAML loaders. Verified by parsing HEAD and the new file with python json.load + yaml.safe_load and diffing entry-by-entry. Under `git diff --histogram`/`--patience` the diff shows zero deletions; the default myers algorithm reports cosmetic deletion lines but they are diff-algorithm noise, not real changes. Where a body field or response shape was clear from the handler, the spec captures it; where the handler accepts free-form / additive JSON payloads the request body is documented as a generic object (additionalProperties: true) rather than a fabricated rigid schema. Better to be honest about flexibility than to lock callers into a wrong type. * docs(openapi): drop nonexistent DELETE /v1/api-keys/{id} The spec carried a DELETE /v1/api-keys/{id} operation, but internal/http/api_keys.go registers no such route — only GET /v1/api-keys, POST /v1/api-keys, and POST /v1/api-keys/{id}/revoke. The DELETE entry predates this PR (it was already on dev), so the semantic-preservation check left it untouched; this removes the stale op so the spec matches the registered routes. The correct POST /v1/api-keys/{id}/revoke operation is unchanged. Verified: json.load parses, go build ./internal/http/ and go vet ./internal/http/ both clean. --------- Co-authored-by: Aaron Vu --- internal/http/openapi_spec.json | 10346 +++++++++++++++++++++++++++++- 1 file changed, 10328 insertions(+), 18 deletions(-) diff --git a/internal/http/openapi_spec.json b/internal/http/openapi_spec.json index 784119e1..db18fa97 100644 --- a/internal/http/openapi_spec.json +++ b/internal/http/openapi_spec.json @@ -36,6 +36,18 @@ { "name": "Storage", "description": "Workspace file management" }, { "name": "Media", "description": "Media upload and serving" }, { "name": "System", "description": "Health check and system info" } + , + { "name": "Vault", "description": "Knowledge Vault: documents, links, search, tree, upload, enrichment" }, + { "name": "Vault Graph", "description": "Lightweight graph view of vault documents + links for visualization" } + , + { "name": "Tenants", "description": "Tenant CRUD and membership" }, + { "name": "CLI Credentials", "description": "Stored CLI binary credentials (claude-cli, codex, ...)" }, + { "name": "Packages", "description": "Runtime + package management" }, + { "name": "Contacts", "description": "Channel contact resolution and merging" }, + { "name": "Teams", "description": "Team workspace + export/import" }, + { "name": "TTS", "description": "Text-to-speech config + synthesis" }, + { "name": "Evolution", "description": "Agent self-evolution metrics + suggestions" }, + { "name": "Episodic Memory", "description": "Episodic session summaries" } ], "security": [{ "bearerAuth": [] }], "paths": { @@ -312,24 +324,6 @@ } } }, - "/v1/api-keys/{id}": { - "delete": { - "tags": ["API Keys"], - "summary": "Revoke an API key", - "description": "Revokes an API key. Revoked keys can no longer be used for authentication. This action cannot be undone.", - "parameters": [ - { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } - ], - "responses": { - "200": { - "description": "Key revoked", - "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "revoked" } } } } } - }, - "401": { "$ref": "#/components/responses/Unauthorized" }, - "404": { "$ref": "#/components/responses/NotFound" } - } - } - }, "/v1/auth/chatgpt/{provider}/quota": { "get": { "tags": ["OAuth"], @@ -1106,6 +1100,55 @@ ], "responses": { "200": { "description": "File listing" } } } + , + "post": { + "tags": [ + "Storage" + ], + "summary": "Upload files (admin)", + "description": "Multipart upload to the tenant workspace.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + } + }, + "path": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } }, "/v1/media/upload": { "post": { @@ -1135,6 +1178,9412 @@ "responses": { "200": { "description": "Group cleared" } } } } + , + "/v1/vault/documents": { + "get": { + "tags": [ + "Vault" + ], + "summary": "List vault documents (tenant-wide)", + "description": "List vault documents across all agents in the tenant. Non-owners see only personal + their teams' docs.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agent_id", + "in": "query", + "schema": { + "type": "string", + "format": "uuid" + }, + "description": "Optional filter by agent." + }, + { + "name": "scope", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "personal", + "team", + "shared" + ] + }, + "description": "Filter by scope. Owner sees all by default; non-owners are restricted to personal + their teams." + }, + { + "name": "doc_type", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of doc_types." + }, + { + "name": "team_id", + "in": "query", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 500 + } + }, + { + "name": "offset", + "in": "query", + "schema": { + "type": "integer", + "default": 0, + "minimum": 0 + } + } + ], + "responses": { + "200": { + "description": "Document list with total count.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "documents": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultDocument" + } + }, + "total": { + "type": "integer" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "post": { + "tags": [ + "Vault" + ], + "summary": "Create vault document (no agent)", + "description": "Create a vault document not bound to a specific agent. When no `team_id` is given the document is shared scope.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultDocumentInput" + } + } + } + }, + "responses": { + "201": { + "description": "Document created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultDocument" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/documents/{docID}": { + "get": { + "tags": [ + "Vault" + ], + "summary": "Get vault document", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "docID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Document found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultDocument" + } + } + } + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "put": { + "tags": [ + "Vault" + ], + "summary": "Update vault document", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "docID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultDocumentUpdateInput" + } + } + } + }, + "responses": { + "200": { + "description": "Document updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultDocument" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "description": "Forbidden — only owner may change team assignment." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "Vault" + ], + "summary": "Delete vault document", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "docID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Document deleted." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/documents/{docID}/links": { + "get": { + "tags": [ + "Vault" + ], + "summary": "Get document outlinks + backlinks", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "docID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Outlinks (with resolved target titles) + backlinks.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "outlinks": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultLink" + } + }, + "backlinks": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultBacklink" + } + }, + "doc_names": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Map of target doc_id → display name." + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/links": { + "post": { + "tags": [ + "Vault" + ], + "summary": "Create vault link", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "from_doc_id", + "to_doc_id" + ], + "properties": { + "from_doc_id": { + "type": "string", + "format": "uuid" + }, + "to_doc_id": { + "type": "string", + "format": "uuid" + }, + "link_type": { + "type": "string", + "default": "reference", + "description": "wikilink, reference, task_attachment, ..." + }, + "context": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Link created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultLink" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "description": "Forbidden — source document not owned by this agent, or cross-team link." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/links/{linkID}": { + "delete": { + "tags": [ + "Vault" + ], + "summary": "Delete vault link", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "linkID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Link deleted." + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/links/batch": { + "post": { + "tags": [ + "Vault" + ], + "summary": "Batch get outlinks", + "description": "Return all outlinks for up to 500 doc_ids in one query.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "doc_ids" + ], + "properties": { + "doc_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "maxItems": 500 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Outlinks.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultLink" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/upload": { + "post": { + "tags": [ + "Vault" + ], + "summary": "Upload files to vault", + "description": "Accept multipart file uploads (up to 50 files, 50 MB each). Files are written to the tenant workspace under `agents/{agent_key}/`, `teams/{team_id}/`, or shared root, depending on form fields. Allowed extensions: md/txt/json/yaml/yml/csv/toml/xml/html/htm/go/py/js/ts/tsx/jsx/rs/java/rb/sh/sql/swift/kt/c/cpp/h.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "required": [ + "files" + ], + "properties": { + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + } + }, + "agent_id": { + "type": "string", + "format": "uuid" + }, + "team_id": { + "type": "string", + "format": "uuid" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Upload result (some files may have errored individually).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "documents": { + "type": "array", + "items": { + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/VaultDocument" + }, + "error": { + "type": "string" + } + } + } + }, + "count": { + "type": "integer", + "description": "Number of files successfully uploaded." + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/rescan": { + "post": { + "tags": [ + "Vault" + ], + "summary": "Rescan tenant workspace", + "description": "Walk the tenant workspace and register missing/changed files. Per-tenant concurrency guard (returns 409 if another rescan is in progress).", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "Rescan complete.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "new": { + "type": "integer" + }, + "updated": { + "type": "integer" + }, + "reenqueued": { + "type": "integer" + }, + "skipped": { + "type": "integer" + } + } + } + } + } + }, + "409": { + "$ref": "#/components/responses/Conflict" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/tree": { + "get": { + "tags": [ + "Vault" + ], + "summary": "List vault tree entries", + "description": "Return immediate children (files + virtual folders) under a path prefix for lazy-loading the vault sidebar.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "path", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Path prefix to expand. Empty = root. Must not contain `..` or start with `/`." + }, + { + "name": "agent_id", + "in": "query", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "scope", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "personal", + "team", + "shared" + ] + } + }, + { + "name": "doc_type", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of doc_types." + }, + { + "name": "team_id", + "in": "query", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Tree entries.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "entries": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultTreeEntry" + } + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/search": { + "post": { + "tags": [ + "Vault" + ], + "summary": "Search vault (tenant-wide)", + "description": "Hybrid full-text + vector search across the tenant. Pass `agent_id` in the body to restrict to one agent.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string" + }, + "agent_id": { + "type": "string", + "format": "uuid", + "description": "Only used by the tenant-wide endpoint. Ignored when the path already carries `{agentID}`." + }, + "scope": { + "type": "string", + "enum": [ + "personal", + "team", + "shared" + ] + }, + "doc_types": { + "type": "array", + "items": { + "type": "string" + } + }, + "max_results": { + "type": "integer", + "default": 10 + }, + "team_id": { + "type": "string", + "format": "uuid" + }, + "chat_id": { + "type": "string", + "description": "Optional. When set with team_id, restrict to same-chat + team-wide docs (isolated semantics)." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Ranked hybrid (FTS + vector) search results.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultSearchResult" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/enrichment/status": { + "get": { + "tags": [ + "Vault" + ], + "summary": "Get enrichment pipeline status", + "description": "Returns current per-tenant enrichment progress (summary generation + embeddings). May return an empty object if no enrichment is running or the worker is disabled.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "Progress snapshot.", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/enrichment/stop": { + "post": { + "tags": [ + "Vault" + ], + "summary": "Stop running enrichment for this tenant", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "Stop signal sent (or no enrichment was running).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "stopped": { + "type": "boolean" + }, + "message": { + "type": "string" + } + } + } + } + } + }, + "503": { + "description": "Enrichment worker not available in this build." + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/vault/documents": { + "get": { + "tags": [ + "Vault" + ], + "summary": "List vault documents for agent", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "scope", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "personal", + "team", + "shared" + ] + }, + "description": "Filter by scope. Owner sees all by default; non-owners are restricted to personal + their teams." + }, + { + "name": "doc_type", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of doc_types." + }, + { + "name": "team_id", + "in": "query", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 500 + } + }, + { + "name": "offset", + "in": "query", + "schema": { + "type": "integer", + "default": 0, + "minimum": 0 + } + } + ], + "responses": { + "200": { + "description": "Document list with total count.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "documents": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultDocument" + } + }, + "total": { + "type": "integer" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "post": { + "tags": [ + "Vault" + ], + "summary": "Create vault document for agent", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultDocumentInput" + } + } + } + }, + "responses": { + "201": { + "description": "Document created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultDocument" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/vault/documents/{docID}": { + "get": { + "tags": [ + "Vault" + ], + "summary": "Get vault document (agent-scoped)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "docID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Document found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultDocument" + } + } + } + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "put": { + "tags": [ + "Vault" + ], + "summary": "Update vault document (agent-scoped)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "docID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultDocumentUpdateInput" + } + } + } + }, + "responses": { + "200": { + "description": "Document updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultDocument" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "description": "Forbidden — only owner may change team assignment." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "Vault" + ], + "summary": "Delete vault document (agent-scoped)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "docID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Document deleted." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/vault/documents/{docID}/links": { + "get": { + "tags": [ + "Vault" + ], + "summary": "Get document links (agent-scoped)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "docID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Outlinks (with resolved target titles) + backlinks.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "outlinks": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultLink" + } + }, + "backlinks": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultBacklink" + } + }, + "doc_names": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Map of target doc_id → display name." + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/vault/search": { + "post": { + "tags": [ + "Vault" + ], + "summary": "Search vault scoped to one agent", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string" + }, + "agent_id": { + "type": "string", + "format": "uuid", + "description": "Only used by the tenant-wide endpoint. Ignored when the path already carries `{agentID}`." + }, + "scope": { + "type": "string", + "enum": [ + "personal", + "team", + "shared" + ] + }, + "doc_types": { + "type": "array", + "items": { + "type": "string" + } + }, + "max_results": { + "type": "integer", + "default": 10 + }, + "team_id": { + "type": "string", + "format": "uuid" + }, + "chat_id": { + "type": "string", + "description": "Optional. When set with team_id, restrict to same-chat + team-wide docs (isolated semantics)." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Ranked hybrid (FTS + vector) search results.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultSearchResult" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/vault/links": { + "post": { + "tags": [ + "Vault" + ], + "summary": "Create vault link (agent-scoped)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "from_doc_id", + "to_doc_id" + ], + "properties": { + "from_doc_id": { + "type": "string", + "format": "uuid" + }, + "to_doc_id": { + "type": "string", + "format": "uuid" + }, + "link_type": { + "type": "string", + "default": "reference", + "description": "wikilink, reference, task_attachment, ..." + }, + "context": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Link created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VaultLink" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "403": { + "description": "Forbidden — source document not owned by this agent, or cross-team link." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/vault/links/{linkID}": { + "delete": { + "tags": [ + "Vault" + ], + "summary": "Delete vault link (agent-scoped)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "linkID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Link deleted." + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/vault/graph": { + "get": { + "tags": [ + "Vault Graph" + ], + "summary": "Vault graph snapshot", + "description": "Lightweight nodes + edges for graph visualization (Cytoscape, etc.). Field names are short to keep wire size small.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agent_id", + "in": "query", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "team_id", + "in": "query", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 2000, + "minimum": 1, + "maximum": 10000 + } + } + ], + "responses": { + "200": { + "description": "Nodes + edges.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultGraphNode" + } + }, + "edges": { + "type": "array", + "items": { + "$ref": "#/components/schemas/VaultGraphEdge" + } + }, + "total_nodes": { + "type": "integer" + }, + "total_edges": { + "type": "integer" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + } + , + "/v1/agents/{agentID}/kg/entities/{entityID}": { + "get": { + "tags": [ + "Knowledge Graph" + ], + "summary": "Get KG entity with relations", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "entityID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "user_id", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Entity + relations.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "entity": { + "$ref": "#/components/schemas/KGEntity" + }, + "relations": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KGRelation" + } + } + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "Knowledge Graph" + ], + "summary": "Delete KG entity", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "entityID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "user_id", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Deleted (status: deleted)." + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/kg/extract": { + "post": { + "tags": [ + "Knowledge Graph" + ], + "summary": "Extract entities + relations from text via LLM", + "description": "Send a text snippet to a configured provider/model; the server runs entity + relation extraction, ingests the result into the KG, and runs inline dedup.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "text", + "provider", + "model" + ], + "properties": { + "text": { + "type": "string" + }, + "user_id": { + "type": "string" + }, + "provider": { + "type": "string" + }, + "model": { + "type": "string" + }, + "min_confidence": { + "type": "number", + "format": "double", + "default": 0.0 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Extraction stats.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "entities": { + "type": "integer" + }, + "relations": { + "type": "integer" + }, + "dedup_merged": { + "type": "integer" + }, + "dedup_flagged": { + "type": "integer" + } + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/kg/stats": { + "get": { + "tags": [ + "Knowledge Graph" + ], + "summary": "KG aggregate statistics", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "user_id", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Stats.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/KGStats" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/kg/graph": { + "get": { + "tags": [ + "Knowledge Graph" + ], + "summary": "Snapshot entities + relations for visualization", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "user_id", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 200, + "minimum": 1, + "maximum": 500 + } + } + ], + "responses": { + "200": { + "description": "Graph snapshot.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "entities": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KGEntity" + } + }, + "relations": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KGRelation" + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/kg/dedup": { + "get": { + "tags": [ + "Knowledge Graph" + ], + "summary": "List pending dedup candidates", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "user_id", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 50 + } + } + ], + "responses": { + "200": { + "description": "Candidates.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/KGDedupCandidate" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/kg/dedup/scan": { + "post": { + "tags": [ + "Knowledge Graph" + ], + "summary": "Scan all entities with embeddings for duplicates", + "description": "Self-join over entity embeddings to flag duplicate candidates above the similarity threshold. Useful for one-off bulk scanning of legacy data.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "user_id": { + "type": "string" + }, + "threshold": { + "type": "number", + "format": "double", + "default": 0.9 + }, + "limit": { + "type": "integer", + "default": 100 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Candidates flagged.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "candidates_found": { + "type": "integer" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/kg/dedup/dismiss": { + "post": { + "tags": [ + "Knowledge Graph" + ], + "summary": "Dismiss a dedup candidate (not a duplicate)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "candidate_id" + ], + "properties": { + "candidate_id": { + "type": "string", + "format": "uuid" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Dismissed." + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/kg/merge": { + "post": { + "tags": [ + "Knowledge Graph" + ], + "summary": "Merge source entity into target", + "description": "Re-points relations from `source_id` to `target_id`, then deletes the source.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "target_id", + "source_id" + ], + "properties": { + "user_id": { + "type": "string" + }, + "target_id": { + "type": "string", + "format": "uuid" + }, + "source_id": { + "type": "string", + "format": "uuid" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Merged." + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/kg/graph/compact": { + "get": { + "tags": [ + "Vault Graph" + ], + "summary": "Compact KG graph snapshot (visualization)", + "description": "Lightweight short-key nodes/edges for graph rendering.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "user_id", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer", + "default": 2000, + "minimum": 1, + "maximum": 10000 + } + } + ], + "responses": { + "200": { + "description": "Nodes + edges.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "nodes": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "n": { + "type": "string", + "description": "name" + }, + "t": { + "type": "string", + "description": "entity_type" + }, + "c": { + "type": "number", + "description": "confidence" + } + } + } + }, + "edges": { + "type": "array", + "items": { + "type": "object" + } + }, + "total_nodes": { + "type": "integer" + }, + "total_edges": { + "type": "integer" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/memory/documents": { + "get": { + "tags": [ + "Memory" + ], + "summary": "List memory documents for agent", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "user_id", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Documents.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MemoryDocument" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/memory/documents/{path...}": { + "get": { + "tags": [ + "Memory" + ], + "summary": "Get memory document", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "path", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Workspace-relative path (`{path...}` route — slashes allowed)." + }, + { + "name": "user_id", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Document.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemoryDocument" + } + } + } + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "put": { + "tags": [ + "Memory" + ], + "summary": "Create or replace memory document", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "path", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Workspace-relative path (`{path...}` route — slashes allowed)." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "content" + ], + "properties": { + "content": { + "type": "string" + }, + "user_id": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "path": { + "type": "string" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "Memory" + ], + "summary": "Delete memory document", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "path", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Workspace-relative path (`{path...}` route — slashes allowed)." + }, + { + "name": "user_id", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Deleted." + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/memory/chunks": { + "get": { + "tags": [ + "Memory" + ], + "summary": "List chunks for a memory document", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "path", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Chunks.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MemoryChunk" + } + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/memory/index": { + "post": { + "tags": [ + "Memory" + ], + "summary": "Index (or re-index) a single memory document", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "type": "string" + }, + "user_id": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/memory/index-all": { + "post": { + "tags": [ + "Memory" + ], + "summary": "Re-index all memory documents for agent", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "user_id": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/auth/chatgpt/{provider}/status": { + "get": { + "tags": [ + "OAuth" + ], + "summary": "OAuth account status", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "provider", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Status.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuthStatus" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/auth/chatgpt/{provider}/start": { + "post": { + "tags": [ + "OAuth" + ], + "summary": "Start OAuth flow", + "description": "Returns an authorization URL the user opens to grant access.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "provider", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "redirect_url": { + "type": "string", + "format": "uri" + }, + "account_name": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Auth URL.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuthStartResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/auth/chatgpt/{provider}/callback": { + "post": { + "tags": [ + "OAuth" + ], + "summary": "Submit manual OAuth callback code", + "description": "Used when the OAuth provider returns the code out-of-band rather than redirecting to the gateway.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "provider", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string" + }, + "state": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/auth/chatgpt/{provider}/logout": { + "post": { + "tags": [ + "OAuth" + ], + "summary": "Log out OAuth account", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "provider", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/auth/openai/status": { + "get": { + "tags": [ + "OAuth" + ], + "summary": "OAuth account status", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "Status.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuthStatus" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/auth/openai/start": { + "post": { + "tags": [ + "OAuth" + ], + "summary": "Start OAuth flow", + "description": "Returns an authorization URL the user opens to grant access.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "redirect_url": { + "type": "string", + "format": "uri" + }, + "account_name": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Auth URL.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuthStartResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/auth/openai/callback": { + "post": { + "tags": [ + "OAuth" + ], + "summary": "Submit manual OAuth callback code", + "description": "Used when the OAuth provider returns the code out-of-band rather than redirecting to the gateway.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string" + }, + "state": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/auth/openai/logout": { + "post": { + "tags": [ + "OAuth" + ], + "summary": "Log out OAuth account", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/storage/files/{path...}": { + "get": { + "tags": [ + "Storage" + ], + "summary": "Read storage file", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "path", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Workspace-relative path (`{path...}` route — slashes allowed)." + } + ], + "responses": { + "200": { + "description": "File content.", + "content": { + "application/octet-stream": {}, + "text/plain": {} + } + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "Storage" + ], + "summary": "Delete storage file (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "path", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Workspace-relative path (`{path...}` route — slashes allowed)." + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/storage/size": { + "get": { + "tags": [ + "Storage" + ], + "summary": "Total storage size in bytes", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "Size.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "size_bytes": { + "type": "integer", + "format": "int64" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/storage/move": { + "put": { + "tags": [ + "Storage" + ], + "summary": "Move storage file (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "src", + "dst" + ], + "properties": { + "src": { + "type": "string" + }, + "dst": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/sync-workspace": { + "post": { + "tags": [ + "Agents" + ], + "summary": "Sync all agents' workspace dirs (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/shares": { + "get": { + "tags": [ + "Agents" + ], + "summary": "List agent shares", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "post": { + "tags": [ + "Agents" + ], + "summary": "Share agent with another user", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "user_id" + ], + "properties": { + "user_id": { + "type": "string" + }, + "role": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/shares/{userID}": { + "delete": { + "tags": [ + "Agents" + ], + "summary": "Revoke agent share", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "userID", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/agents/{id}/regenerate": { + "post": { + "tags": [ + "Agents" + ], + "summary": "Regenerate agent identity files", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/resummon": { + "post": { + "tags": [ + "Agents" + ], + "summary": "Re-run agent summon pipeline", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/cancel-summon": { + "post": { + "tags": [ + "Agents" + ], + "summary": "Cancel in-progress summon", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/system-prompt-preview": { + "get": { + "tags": [ + "Agents" + ], + "summary": "Preview the rendered system prompt", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/export": { + "get": { + "tags": [ + "Agents" + ], + "summary": "Trigger agent export (returns download token)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/export/preview": { + "get": { + "tags": [ + "Agents" + ], + "summary": "Dry-run preview of agent export", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/export/download/{token}": { + "get": { + "tags": [ + "Agents" + ], + "summary": "Download a previously-issued agent export bundle", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "token", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Tarball.", + "content": { + "application/gzip": {}, + "application/octet-stream": {} + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/export/download/{token}": { + "get": { + "tags": [ + "Agents" + ], + "summary": "Download an export bundle by token (alternate URL)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "token", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Tarball.", + "content": { + "application/gzip": {}, + "application/octet-stream": {} + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/import/preview": { + "post": { + "tags": [ + "Agents" + ], + "summary": "Dry-run preview of an agent import", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/import": { + "post": { + "tags": [ + "Agents" + ], + "summary": "Import an agent bundle", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/import": { + "post": { + "tags": [ + "Agents" + ], + "summary": "Merge-import additional content into an existing agent", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/instances": { + "get": { + "tags": [ + "Agents" + ], + "summary": "List per-user agent instances", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/instances/{userID}/files": { + "get": { + "tags": [ + "Agents" + ], + "summary": "List per-user agent context files", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "userID", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{id}/instances/{userID}/metadata": { + "patch": { + "tags": [ + "Agents" + ], + "summary": "Patch per-user agent instance metadata", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "userID", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/orchestration": { + "get": { + "tags": [ + "Agents" + ], + "summary": "Get agent orchestration config + mode", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/v3-flags": { + "get": { + "tags": [ + "Agents" + ], + "summary": "Get v3 feature flags for agent", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "patch": { + "tags": [ + "Agents" + ], + "summary": "Update v3 feature flags for agent", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/evolution/metrics": { + "get": { + "tags": [ + "Evolution" + ], + "summary": "List agent evolution metrics", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "metric_type", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "Metrics.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EvolutionMetric" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/evolution/suggestions": { + "get": { + "tags": [ + "Evolution" + ], + "summary": "List agent evolution suggestions", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "status", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Suggestions.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EvolutionSuggestion" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/evolution/suggestions/{suggestionID}": { + "patch": { + "tags": [ + "Evolution" + ], + "summary": "Review an evolution suggestion (accept/reject/apply/revert)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "suggestionID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "status" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "accepted", + "rejected", + "applied", + "reverted" + ] + }, + "reviewer": { + "type": "string" + }, + "notes": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/episodic": { + "get": { + "tags": [ + "Episodic Memory" + ], + "summary": "List episodic summaries for agent", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "user_id", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "Episodic summaries.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EpisodicSummary" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/episodic/search": { + "post": { + "tags": [ + "Episodic Memory" + ], + "summary": "Hybrid search over episodic summaries", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string" + }, + "user_id": { + "type": "string" + }, + "max_results": { + "type": "integer", + "default": 10 + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/agents/{agentID}/skills": { + "get": { + "tags": [ + "Skills" + ], + "summary": "List skills granted to agent", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/{id}/versions": { + "get": { + "tags": [ + "Skills" + ], + "summary": "List skill versions", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/{id}/files": { + "get": { + "tags": [ + "Skills" + ], + "summary": "List files inside a skill bundle", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/{id}/files/{path...}": { + "get": { + "tags": [ + "Skills" + ], + "summary": "Read a file inside a skill bundle", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "path", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Workspace-relative path (`{path...}` route — slashes allowed)." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/upload": { + "post": { + "tags": [ + "Skills" + ], + "summary": "Upload a skill bundle (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/{id}/grants/agent": { + "post": { + "tags": [ + "Skills" + ], + "summary": "Grant skill to an agent (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "agent_id" + ], + "properties": { + "agent_id": { + "type": "string", + "format": "uuid" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/{id}/grants/agent/{agentID}": { + "delete": { + "tags": [ + "Skills" + ], + "summary": "Revoke skill from agent (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/skills/{id}/grants/user": { + "post": { + "tags": [ + "Skills" + ], + "summary": "Grant skill to a user (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "user_id" + ], + "properties": { + "user_id": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/{id}/grants/user/{userID}": { + "delete": { + "tags": [ + "Skills" + ], + "summary": "Revoke skill from user (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "userID", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/skills/rescan-deps": { + "post": { + "tags": [ + "Skills" + ], + "summary": "Rescan installed skill dependencies (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/install-deps": { + "post": { + "tags": [ + "Skills" + ], + "summary": "Install dependencies for all skills (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/install-dep": { + "post": { + "tags": [ + "Skills" + ], + "summary": "Install a single dependency (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "runtime", + "name" + ], + "properties": { + "runtime": { + "type": "string", + "enum": [ + "npm", + "pip", + "go", + "system" + ] + }, + "name": { + "type": "string" + }, + "version": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/runtimes": { + "get": { + "tags": [ + "Skills" + ], + "summary": "List supported skill runtimes (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/{id}/toggle": { + "post": { + "tags": [ + "Skills" + ], + "summary": "Enable / disable a skill (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/{id}/tenant-config": { + "put": { + "tags": [ + "Skills" + ], + "summary": "Set tenant-scoped config for a skill (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "Skills" + ], + "summary": "Reset tenant-scoped skill config (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/skills/export/preview": { + "get": { + "tags": [ + "Skills" + ], + "summary": "Preview a skill-set export bundle (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/export": { + "get": { + "tags": [ + "Skills" + ], + "summary": "Export a skill-set bundle (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "Tarball.", + "content": { + "application/gzip": {} + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/skills/import": { + "post": { + "tags": [ + "Skills" + ], + "summary": "Import a skill-set bundle (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/mcp/servers/test": { + "post": { + "tags": [ + "MCP Servers" + ], + "summary": "Test MCP server connection without saving (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "transport" + ], + "properties": { + "transport": { + "type": "string", + "enum": [ + "stdio", + "http", + "sse", + "websocket" + ] + }, + "command": { + "type": "string" + }, + "url": { + "type": "string" + }, + "env": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/mcp/servers/{id}/reconnect": { + "post": { + "tags": [ + "MCP Servers" + ], + "summary": "Force reconnect to MCP server (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/mcp/servers/{id}/grants": { + "get": { + "tags": [ + "MCP Servers" + ], + "summary": "List grants on this MCP server", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/mcp/servers/{id}/grants/agent": { + "post": { + "tags": [ + "MCP Servers" + ], + "summary": "Grant agent access to MCP server (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "agent_id" + ], + "properties": { + "agent_id": { + "type": "string", + "format": "uuid" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/mcp/servers/{id}/grants/agent/{agentID}": { + "delete": { + "tags": [ + "MCP Servers" + ], + "summary": "Revoke agent MCP grant (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/mcp/servers/{id}/grants/user": { + "post": { + "tags": [ + "MCP Servers" + ], + "summary": "Grant user access to MCP server (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "user_id" + ], + "properties": { + "user_id": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/mcp/servers/{id}/grants/user/{userID}": { + "delete": { + "tags": [ + "MCP Servers" + ], + "summary": "Revoke user MCP grant (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "userID", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/mcp/servers/{id}/user-credentials": { + "get": { + "tags": [ + "MCP Servers" + ], + "summary": "Get per-user MCP credentials (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "put": { + "tags": [ + "MCP Servers" + ], + "summary": "Set per-user MCP credentials (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "MCP Servers" + ], + "summary": "Clear per-user MCP credentials (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/mcp/grants/agent/{agentID}": { + "get": { + "tags": [ + "MCP Servers" + ], + "summary": "List all MCP grants for one agent", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "agentID", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/mcp/requests": { + "get": { + "tags": [ + "MCP Servers" + ], + "summary": "List pending MCP requests", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "post": { + "tags": [ + "MCP Servers" + ], + "summary": "Create an MCP request (delegated call requiring approval)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/mcp/requests/{id}/review": { + "post": { + "tags": [ + "MCP Servers" + ], + "summary": "Approve or reject an MCP request (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "decision" + ], + "properties": { + "decision": { + "type": "string", + "enum": [ + "approve", + "reject" + ] + }, + "comment": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/mcp/export": { + "get": { + "tags": [ + "MCP Servers" + ], + "summary": "Export MCP server set (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "Bundle.", + "content": { + "application/gzip": {}, + "application/json": {} + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/mcp/export/preview": { + "get": { + "tags": [ + "MCP Servers" + ], + "summary": "Preview MCP server export (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/mcp/import": { + "post": { + "tags": [ + "MCP Servers" + ], + "summary": "Import MCP server set (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/providers/{id}/verify-embedding": { + "post": { + "tags": [ + "Providers" + ], + "summary": "Verify provider's embedding endpoint", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "model": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/providers/{id}/codex-pool-activity": { + "get": { + "tags": [ + "Providers" + ], + "summary": "Codex pool activity for one provider", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/providers/claude-cli/auth-status": { + "get": { + "tags": [ + "Providers" + ], + "summary": "Aggregate Claude-CLI provider auth status", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/embedding/status": { + "get": { + "tags": [ + "Providers" + ], + "summary": "Embedding subsystem status across providers", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tenants": { + "get": { + "tags": [ + "Tenants" + ], + "summary": "List tenants (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "Tenants.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Tenant" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "post": { + "tags": [ + "Tenants" + ], + "summary": "Create tenant (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "slug", + "name" + ], + "properties": { + "slug": { + "type": "string" + }, + "name": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Created" + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tenants/{id}": { + "get": { + "tags": [ + "Tenants" + ], + "summary": "Get tenant", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Tenant.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Tenant" + } + } + } + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "patch": { + "tags": [ + "Tenants" + ], + "summary": "Update tenant", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tenants/{id}/users": { + "get": { + "tags": [ + "Tenants" + ], + "summary": "List tenant users", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Users.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TenantUser" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "post": { + "tags": [ + "Tenants" + ], + "summary": "Add user to tenant", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "user_id" + ], + "properties": { + "user_id": { + "type": "string" + }, + "role": { + "type": "string", + "enum": [ + "admin", + "operator", + "viewer" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tenants/{id}/users/{userId}": { + "delete": { + "tags": [ + "Tenants" + ], + "summary": "Remove user from tenant", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "userId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/tenant-users": { + "get": { + "tags": [ + "Tenants" + ], + "summary": "List the calling user's tenant memberships", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "Memberships.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TenantUser" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/users/search": { + "get": { + "tags": [ + "Tenants" + ], + "summary": "Search users by name/email", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "q", + "in": "query", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/cli-credentials": { + "get": { + "tags": [ + "CLI Credentials" + ], + "summary": "List configured CLI credential presets", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "Credentials.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CLICredential" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "post": { + "tags": [ + "CLI Credentials" + ], + "summary": "Create CLI credential preset", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "201": { + "description": "Created" + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/cli-credentials/presets": { + "get": { + "tags": [ + "CLI Credentials" + ], + "summary": "List built-in CLI credential presets", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/cli-credentials/check-binary": { + "post": { + "tags": [ + "CLI Credentials" + ], + "summary": "Probe a CLI binary on the server", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "binary" + ], + "properties": { + "binary": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/cli-credentials/{id}": { + "get": { + "tags": [ + "CLI Credentials" + ], + "summary": "Get CLI credential preset", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "put": { + "tags": [ + "CLI Credentials" + ], + "summary": "Update CLI credential preset", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "CLI Credentials" + ], + "summary": "Delete CLI credential preset", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/cli-credentials/{id}/test": { + "post": { + "tags": [ + "CLI Credentials" + ], + "summary": "Dry-run test the CLI preset", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/cli-credentials/{id}/user-credentials": { + "get": { + "tags": [ + "CLI Credentials" + ], + "summary": "List per-user credentials under this preset", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/cli-credentials/{id}/user-credentials/{userId}": { + "get": { + "tags": [ + "CLI Credentials" + ], + "summary": "Get per-user credential", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "userId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "put": { + "tags": [ + "CLI Credentials" + ], + "summary": "Set per-user credential", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "userId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "CLI Credentials" + ], + "summary": "Delete per-user credential", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "userId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/cli-credentials/{id}/agent-grants": { + "get": { + "tags": [ + "CLI Credentials" + ], + "summary": "List agent grants on a CLI credential", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "post": { + "tags": [ + "CLI Credentials" + ], + "summary": "Grant agent access to CLI credential", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "agent_id" + ], + "properties": { + "agent_id": { + "type": "string", + "format": "uuid" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/cli-credentials/{id}/agent-grants/{grantId}": { + "get": { + "tags": [ + "CLI Credentials" + ], + "summary": "Get an agent grant", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "grantId", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "put": { + "tags": [ + "CLI Credentials" + ], + "summary": "Update an agent grant", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "grantId", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "CLI Credentials" + ], + "summary": "Delete an agent grant", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "grantId", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/system-configs": { + "get": { + "tags": [ + "System" + ], + "summary": "List system config keys", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/system-configs/{key}": { + "get": { + "tags": [ + "System" + ], + "summary": "Get a system config value", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "key", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "put": { + "tags": [ + "System" + ], + "summary": "Set a system config value (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "key", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "System" + ], + "summary": "Reset a system config value (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "key", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/edition": { + "get": { + "tags": [ + "System" + ], + "summary": "Edition info (Lite/Standard) + feature limits", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/openapi.json": { + "get": { + "tags": [ + "System" + ], + "summary": "OpenAPI spec", + "description": "Returns the spec served by Swagger UI. Useful for client codegen.", + "responses": { + "200": { + "description": "OpenAPI 3 spec.", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + } + } + } + }, + "/v1/system/backup": { + "post": { + "tags": [ + "System" + ], + "summary": "Trigger a system backup (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "Backup queued / completed.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "token": { + "type": "string" + }, + "size_bytes": { + "type": "integer" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/system/backup/preflight": { + "get": { + "tags": [ + "System" + ], + "summary": "Preflight check for backup", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/system/backup/download/{token}": { + "get": { + "tags": [ + "System" + ], + "summary": "Download backup bundle", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "token", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Bundle.", + "content": { + "application/gzip": {} + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/system/backup/s3/config": { + "get": { + "tags": [ + "System" + ], + "summary": "Get S3 backup config", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "put": { + "tags": [ + "System" + ], + "summary": "Set S3 backup config (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/system/backup/s3/list": { + "get": { + "tags": [ + "System" + ], + "summary": "List backups in the configured S3 bucket", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/system/backup/s3/backup": { + "post": { + "tags": [ + "System" + ], + "summary": "Trigger backup directly to S3 (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/system/backup/s3/upload": { + "post": { + "tags": [ + "System" + ], + "summary": "Upload existing backup to S3 (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "token" + ], + "properties": { + "token": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/system/restore": { + "post": { + "tags": [ + "System" + ], + "summary": "Restore system from a backup bundle (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tenant/backup": { + "post": { + "tags": [ + "System" + ], + "summary": "Trigger tenant-scoped backup", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tenant/backup/preflight": { + "get": { + "tags": [ + "System" + ], + "summary": "Preflight check for tenant backup", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tenant/backup/download/{token}": { + "get": { + "tags": [ + "System" + ], + "summary": "Download tenant backup bundle", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "token", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Bundle.", + "content": { + "application/gzip": {} + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tenant/restore": { + "post": { + "tags": [ + "System" + ], + "summary": "Restore tenant from a backup bundle", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/packages": { + "get": { + "tags": [ + "Packages" + ], + "summary": "List packages tracked by goclaw", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "Packages.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Package" + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/packages/install": { + "post": { + "tags": [ + "Packages" + ], + "summary": "Install a package (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "runtime", + "name" + ], + "properties": { + "runtime": { + "type": "string", + "enum": [ + "npm", + "pip", + "go", + "system" + ] + }, + "name": { + "type": "string" + }, + "version": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/packages/uninstall": { + "post": { + "tags": [ + "Packages" + ], + "summary": "Uninstall a package (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "runtime", + "name" + ], + "properties": { + "runtime": { + "type": "string" + }, + "name": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/packages/runtimes": { + "get": { + "tags": [ + "Packages" + ], + "summary": "List installed runtimes (node/python/go)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/packages/github-releases": { + "get": { + "tags": [ + "Packages" + ], + "summary": "Resolve GitHub-release-backed package versions", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "repo", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/shell-deny-groups": { + "get": { + "tags": [ + "Packages" + ], + "summary": "Runtime shell-deny groups config", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tools/builtin/{name}/tenant-config": { + "get": { + "tags": [ + "Built-in Tools" + ], + "summary": "Get tenant-scoped config for a built-in tool", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "put": { + "tags": [ + "Built-in Tools" + ], + "summary": "Set tenant-scoped config for a built-in tool (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "delete": { + "tags": [ + "Built-in Tools" + ], + "summary": "Reset tenant-scoped tool config (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/tts/config": { + "get": { + "tags": [ + "TTS" + ], + "summary": "Get TTS config", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "post": { + "tags": [ + "TTS" + ], + "summary": "Set TTS config", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tts/synthesize": { + "post": { + "tags": [ + "TTS" + ], + "summary": "Synthesize speech", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "text" + ], + "properties": { + "text": { + "type": "string" + }, + "voice_id": { + "type": "string" + }, + "provider": { + "type": "string" + }, + "model": { + "type": "string" + }, + "params": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Audio.", + "content": { + "audio/mpeg": {}, + "audio/wav": {}, + "audio/ogg": {} + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tts/test-connection": { + "post": { + "tags": [ + "TTS" + ], + "summary": "Probe TTS provider connectivity", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "provider": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/tts/capabilities": { + "get": { + "tags": [ + "TTS" + ], + "summary": "Capabilities matrix of configured TTS providers", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/voices": { + "get": { + "tags": [ + "TTS" + ], + "summary": "List available TTS voices", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/voices/refresh": { + "post": { + "tags": [ + "TTS" + ], + "summary": "Refresh voice catalog from providers (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/teams/{id}/export/preview": { + "get": { + "tags": [ + "Teams" + ], + "summary": "Preview a team export (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/teams/{id}/export": { + "get": { + "tags": [ + "Teams" + ], + "summary": "Export a team (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Tarball.", + "content": { + "application/gzip": {} + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/teams/import": { + "post": { + "tags": [ + "Teams" + ], + "summary": "Import a team (admin)", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "file": { + "type": "string", + "format": "binary" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/teams/{teamId}/workspace/upload": { + "post": { + "tags": [ + "Teams" + ], + "summary": "Upload files to team workspace", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "teamId", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "files": { + "type": "array", + "items": { + "type": "string", + "format": "binary" + } + }, + "path": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/teams/{teamId}/workspace/move": { + "put": { + "tags": [ + "Teams" + ], + "summary": "Move file in team workspace", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "teamId", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "src", + "dst" + ], + "properties": { + "src": { + "type": "string" + }, + "dst": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/teams/{id}/events": { + "get": { + "tags": [ + "Teams" + ], + "summary": "Team event log", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/teams/{teamId}/attachments/{attachmentId}/download": { + "get": { + "tags": [ + "Teams" + ], + "summary": "Download a team task attachment", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "teamId", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "attachmentId", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "File.", + "content": { + "application/octet-stream": {} + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/channels/instances/{id}/writers": { + "get": { + "tags": [ + "Channels" + ], + "summary": "List configured writers on a channel instance", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + }, + "post": { + "tags": [ + "Channels" + ], + "summary": "Add a writer to a channel instance", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "user_id" + ], + "properties": { + "user_id": { + "type": "string" + }, + "role": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/channels/instances/{id}/writers/{userId}": { + "delete": { + "tags": [ + "Channels" + ], + "summary": "Remove a writer from a channel instance", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "userId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Deleted" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "404": { + "$ref": "#/components/responses/NotFound" + } + } + } + }, + "/v1/channels/instances/{id}/writers/groups": { + "get": { + "tags": [ + "Channels" + ], + "summary": "List writer groups available on this channel", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/contacts/resolve": { + "get": { + "tags": [ + "Contacts" + ], + "summary": "Resolve a channel contact to a unified user", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "channel", + "in": "query", + "schema": { + "type": "string" + } + }, + { + "name": "external_id", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/contacts/merged/{tenantUserId}": { + "get": { + "tags": [ + "Contacts" + ], + "summary": "Show merged contact bundle for a tenant user", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "tenantUserId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/contacts/merge": { + "post": { + "tags": [ + "Contacts" + ], + "summary": "Merge two contacts", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "target_id", + "source_id" + ], + "properties": { + "target_id": { + "type": "string" + }, + "source_id": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/contacts/unmerge": { + "post": { + "tags": [ + "Contacts" + ], + "summary": "Unmerge a previously-merged contact", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "contact_id" + ], + "properties": { + "contact_id": { + "type": "string" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/pending-messages/messages": { + "get": { + "tags": [ + "Channels" + ], + "summary": "List pending channel messages", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/pending-messages/compact": { + "post": { + "tags": [ + "Channels" + ], + "summary": "Compact / collapse pending messages", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/files/{path...}": { + "get": { + "tags": [ + "Storage" + ], + "summary": "Read agent workspace file", + "description": "Reads a file in the calling agent's workspace (or, with admin, any path). Used by the web UI's file browser.", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "path", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "Workspace-relative path (`{path...}` route — slashes allowed)." + } + ], + "responses": { + "200": { + "description": "File content.", + "content": { + "application/octet-stream": {}, + "text/plain": {} + } + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/files/sign": { + "post": { + "tags": [ + "Storage" + ], + "summary": "Sign a file URL for temporary public access", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "type": "string" + }, + "expires_in": { + "type": "integer", + "description": "Expiry in seconds." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/traces/{traceID}/export": { + "get": { + "tags": [ + "Traces" + ], + "summary": "Export full trace as JSON", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "traceID", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Trace bundle.", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "404": { + "$ref": "#/components/responses/NotFound" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/usage/breakdown": { + "get": { + "tags": [ + "Usage" + ], + "summary": "Usage breakdown by agent/provider/model", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "from", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "to", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + } + }, + { + "name": "group_by", + "in": "query", + "schema": { + "type": "string", + "enum": [ + "agent", + "provider", + "model" + ] + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + }, + "/v1/api-keys/{id}/revoke": { + "post": { + "tags": [ + "API Keys" + ], + "summary": "Revoke an API key", + "parameters": [ + { + "name": "X-GoClaw-User-Id", + "in": "header", + "required": true, + "schema": { + "type": "string" + }, + "description": "External user ID for multi-tenant context." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + } + } + } + } }, "components": { "securitySchemes": { @@ -1253,7 +10702,868 @@ "error": { "type": "string" } } } + , + "VaultDocument": { + "type": "object", + "description": "Document registered in the Knowledge Vault. Content lives on disk in the tenant workspace; the registry holds metadata + summary + embedding + links.", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "tenant_id": { + "type": "string", + "format": "uuid" + }, + "agent_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Owning agent. Null for team or shared documents." + }, + "team_id": { + "type": "string", + "format": "uuid", + "nullable": true + }, + "chat_id": { + "type": "string", + "nullable": true, + "description": "Set only in isolated teams to scope a document to one chat." + }, + "scope": { + "type": "string", + "enum": [ + "personal", + "team", + "shared" + ] + }, + "custom_scope": { + "type": "string", + "nullable": true + }, + "path": { + "type": "string", + "description": "Workspace-relative path." + }, + "path_basename": { + "type": "string" + }, + "title": { + "type": "string" + }, + "doc_type": { + "type": "string", + "enum": [ + "context", + "memory", + "note", + "skill", + "episodic", + "media" + ] + }, + "content_hash": { + "type": "string", + "description": "SHA-256 hex digest of the file." + }, + "summary": { + "type": "string" + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } }, + "VaultDocumentInput": { + "type": "object", + "required": [ + "path", + "title" + ], + "properties": { + "path": { + "type": "string", + "example": "specs/PRD-checkout.md", + "description": "Workspace-relative path. Must not contain `..` or start with `/`." + }, + "title": { + "type": "string" + }, + "doc_type": { + "type": "string", + "default": "note", + "enum": [ + "context", + "memory", + "note", + "skill", + "episodic", + "media" + ] + }, + "scope": { + "type": "string", + "default": "personal", + "enum": [ + "personal", + "team", + "shared" + ] + }, + "team_id": { + "type": "string", + "format": "uuid", + "description": "When set, the request must be made by a member of the team. Implies scope=team." + }, + "metadata": { + "type": "object", + "additionalProperties": true + } + } + }, + "VaultDocumentUpdateInput": { + "type": "object", + "description": "Partial update. Omitted fields are left unchanged. `team_id`: nil = no change, `\"\"` = clear (back to personal), uuid = move to team (owner only).", + "properties": { + "title": { + "type": "string" + }, + "doc_type": { + "type": "string" + }, + "scope": { + "type": "string", + "enum": [ + "personal", + "team", + "shared" + ] + }, + "team_id": { + "type": "string", + "nullable": true + }, + "metadata": { + "type": "object", + "additionalProperties": true + } + } + }, + "VaultLink": { + "type": "object", + "description": "Directed link between two vault documents (wikilink, reference, attachment, ...).", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "from_doc_id": { + "type": "string", + "format": "uuid" + }, + "to_doc_id": { + "type": "string", + "format": "uuid" + }, + "link_type": { + "type": "string", + "example": "wikilink" + }, + "context": { + "type": "string", + "description": "Surrounding text snippet or source reference." + }, + "metadata": { + "type": "object", + "additionalProperties": true, + "nullable": true + }, + "created_at": { + "type": "string", + "format": "date-time" + } + } + }, + "VaultBacklink": { + "type": "object", + "description": "Enriched backlink: source doc metadata joined with the link row.", + "properties": { + "from_doc_id": { + "type": "string", + "format": "uuid" + }, + "context": { + "type": "string" + }, + "title": { + "type": "string" + }, + "path": { + "type": "string" + }, + "team_id": { + "type": "string", + "format": "uuid", + "nullable": true + } + } + }, + "VaultSearchResult": { + "type": "object", + "properties": { + "document": { + "$ref": "#/components/schemas/VaultDocument" + }, + "score": { + "type": "number", + "format": "double" + }, + "source": { + "type": "string", + "enum": [ + "vault", + "episodic", + "kg" + ] + } + } + }, + "VaultTreeEntry": { + "type": "object", + "description": "A file or virtual folder under a tree path.", + "properties": { + "name": { + "type": "string" + }, + "path": { + "type": "string" + }, + "isDir": { + "type": "boolean" + }, + "hasChildren": { + "type": "boolean" + }, + "docId": { + "type": "string", + "format": "uuid" + }, + "docType": { + "type": "string" + }, + "scope": { + "type": "string" + }, + "title": { + "type": "string" + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + }, + "VaultGraphNode": { + "type": "object", + "description": "Lightweight vault doc for graph visualization. Field names are intentionally short to keep wire size small.", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "t": { + "type": "string", + "description": "title" + }, + "p": { + "type": "string", + "description": "path" + }, + "dt": { + "type": "string", + "description": "doc_type" + }, + "deg": { + "type": "integer", + "description": "in+out degree" + } + } + }, + "VaultGraphEdge": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "from": { + "type": "string", + "format": "uuid" + }, + "to": { + "type": "string", + "format": "uuid" + }, + "type": { + "type": "string", + "description": "link_type" + } + } + } + , + "KGEntity": { + "type": "object", + "description": "Knowledge Graph entity. `external_id` is the caller-supplied stable identifier; `id` is the server-assigned UUID.", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "agent_id": { + "type": "string", + "format": "uuid" + }, + "user_id": { + "type": "string" + }, + "external_id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "entity_type": { + "type": "string" + }, + "description": { + "type": "string" + }, + "properties": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "source_id": { + "type": "string" + }, + "confidence": { + "type": "number", + "format": "double" + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "updated_at": { + "type": "integer", + "format": "int64" + } + }, + "required": [ + "external_id", + "name", + "entity_type" + ] + }, + "KGRelation": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "agent_id": { + "type": "string", + "format": "uuid" + }, + "user_id": { + "type": "string" + }, + "source_entity_id": { + "type": "string", + "format": "uuid" + }, + "relation_type": { + "type": "string" + }, + "target_entity_id": { + "type": "string", + "format": "uuid" + }, + "confidence": { + "type": "number", + "format": "double" + }, + "properties": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "created_at": { + "type": "integer", + "format": "int64" + }, + "valid_from": { + "type": "string", + "format": "date-time", + "nullable": true + }, + "valid_until": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + }, + "KGDedupCandidate": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "entity_a": { + "$ref": "#/components/schemas/KGEntity" + }, + "entity_b": { + "$ref": "#/components/schemas/KGEntity" + }, + "similarity": { + "type": "number", + "format": "double" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "dismissed", + "merged" + ] + }, + "created_at": { + "type": "integer", + "format": "int64" + } + } + }, + "KGStats": { + "type": "object", + "properties": { + "entity_count": { + "type": "integer" + }, + "relation_count": { + "type": "integer" + }, + "entity_types": { + "type": "object", + "additionalProperties": { + "type": "integer" + } + }, + "user_ids": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "TraversalResult": { + "type": "object", + "properties": { + "entity": { + "$ref": "#/components/schemas/KGEntity" + }, + "depth": { + "type": "integer" + }, + "path": { + "type": "array", + "items": { + "type": "string" + } + }, + "via": { + "type": "string" + } + } + }, + "MemoryDocument": { + "type": "object", + "properties": { + "agent_id": { + "type": "string", + "format": "uuid" + }, + "user_id": { + "type": "string" + }, + "path": { + "type": "string" + }, + "content": { + "type": "string" + }, + "size": { + "type": "integer" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, + "MemoryChunk": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "path": { + "type": "string" + }, + "start_line": { + "type": "integer" + }, + "end_line": { + "type": "integer" + }, + "text": { + "type": "string" + } + } + }, + "MemorySearchHit": { + "type": "object", + "properties": { + "path": { + "type": "string" + }, + "text": { + "type": "string" + }, + "score": { + "type": "number", + "format": "double" + } + } + }, + "OAuthStatus": { + "type": "object", + "properties": { + "authenticated": { + "type": "boolean" + }, + "account_name": { + "type": "string" + }, + "expires_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + }, + "OAuthStartResponse": { + "type": "object", + "properties": { + "auth_url": { + "type": "string", + "format": "uri" + }, + "state": { + "type": "string" + } + } + }, + "Skill": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string" + }, + "version": { + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "system": { + "type": "boolean" + }, + "metadata": { + "type": "object", + "additionalProperties": true + } + } + }, + "McpServer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "transport": { + "type": "string", + "enum": [ + "stdio", + "http", + "sse", + "websocket" + ] + }, + "command": { + "type": "string" + }, + "url": { + "type": "string" + }, + "enabled": { + "type": "boolean" + }, + "tenant_id": { + "type": "string", + "format": "uuid" + } + } + }, + "Tenant": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "slug": { + "type": "string" + }, + "name": { + "type": "string" + }, + "created_at": { + "type": "string", + "format": "date-time" + } + } + }, + "TenantUser": { + "type": "object", + "properties": { + "tenant_id": { + "type": "string", + "format": "uuid" + }, + "user_id": { + "type": "string" + }, + "role": { + "type": "string", + "enum": [ + "admin", + "operator", + "viewer" + ] + }, + "added_at": { + "type": "string", + "format": "date-time" + } + } + }, + "CLICredential": { + "type": "object", + "description": "Stored authentication binary preset for a CLI provider (claude-cli, codex, etc).", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "name": { + "type": "string" + }, + "binary_name": { + "type": "string" + }, + "preset": { + "type": "string" + }, + "scope": { + "type": "string" + }, + "metadata": { + "type": "object", + "additionalProperties": true + }, + "created_at": { + "type": "string", + "format": "date-time" + } + } + }, + "Package": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "runtime": { + "type": "string", + "enum": [ + "npm", + "pip", + "go", + "system" + ] + }, + "installed": { + "type": "boolean" + }, + "version": { + "type": "string" + } + } + }, + "EvolutionMetric": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "agent_id": { + "type": "string", + "format": "uuid" + }, + "metric_type": { + "type": "string" + }, + "metric_key": { + "type": "string" + }, + "value": { + "type": "object", + "additionalProperties": true + }, + "created_at": { + "type": "string", + "format": "date-time" + } + } + }, + "EvolutionSuggestion": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "agent_id": { + "type": "string", + "format": "uuid" + }, + "suggestion_type": { + "type": "string" + }, + "suggestion": { + "type": "string" + }, + "rationale": { + "type": "string" + }, + "parameters": { + "type": "object", + "additionalProperties": true + }, + "status": { + "type": "string", + "enum": [ + "pending", + "accepted", + "rejected", + "applied", + "reverted" + ] + }, + "created_at": { + "type": "string", + "format": "date-time" + } + } + }, + "EpisodicSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "agent_id": { + "type": "string", + "format": "uuid" + }, + "user_id": { + "type": "string" + }, + "session_key": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "l0_abstract": { + "type": "string" + }, + "key_topics": { + "type": "array", + "items": { + "type": "string" + } + }, + "turn_count": { + "type": "integer" + }, + "token_count": { + "type": "integer" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "expires_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + }, "responses": { "Unauthorized": { "description": "Authentication required or invalid token",