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",