mirror of
https://github.com/tiennm99/goclaw.git
synced 2026-10-04 22:13:34 +00:00
Dmitry
2810ad96f0
Approved by github-maintain. Clean implementation of AI/ML API as branded OpenAI-compatible provider. All CI green. Closes #1325.
11589 lines
310 KiB
JSON
11589 lines
310 KiB
JSON
{
|
|
"openapi": "3.0.3",
|
|
"info": {
|
|
"title": "GoClaw Gateway API",
|
|
"description": "PostgreSQL multi-tenant AI agent gateway with WebSocket RPC + HTTP API.\n\n## Authentication\n\nAll endpoints require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer <gateway-token-or-api-key>\n```\n\nYou can use either the **gateway token** (grants admin access) or an **API key** created via the API Keys endpoints (grants scoped access).\n\nIf no gateway token is configured, empty-token admin access is limited to loopback local development or explicit `GOCLAW_ALLOW_INSECURE_NO_AUTH=1`; externally reachable deployments require `GOCLAW_GATEWAY_TOKEN`.\n\n## Common Headers\n\n| Header | Description |\n|--------|-------------|\n| `X-GoClaw-User-Id` | External user ID for multi-tenant context |\n| `X-GoClaw-Agent-Id` | Target agent ID (alternative to model prefix) |\n| `X-GoClaw-Tenant-Id` | Tenant scope — UUID or slug (gateway token / cross-tenant API keys) |\n| `Accept-Language` | Locale for error messages (`en`, `vi`, `zh`) |\n\n## WebSocket Protocol\n\nConnect via `POST /ws` (upgrade). Protocol v3 uses frame types: `req`, `res`, `event`.\nFirst request must be `connect` with `{\"token\": \"...\", \"user_id\": \"...\", \"locale\": \"en\"}`.",
|
|
"version": "0.2.0",
|
|
"contact": {
|
|
"name": "GoClaw",
|
|
"url": "https://github.com/nextlevelbuilder/goclaw"
|
|
}
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "/",
|
|
"description": "Current server"
|
|
}
|
|
],
|
|
"tags": [
|
|
{ "name": "Chat", "description": "OpenAI-compatible chat completions" },
|
|
{ "name": "API Keys", "description": "Gateway API key management (admin only)" },
|
|
{ "name": "Agents", "description": "Agent CRUD and configuration" },
|
|
{ "name": "Sessions", "description": "Chat session management (via WebSocket RPC)" },
|
|
{ "name": "Providers", "description": "LLM provider configuration" },
|
|
{ "name": "OAuth", "description": "Provider-scoped OAuth status and quota endpoints" },
|
|
{ "name": "Skills", "description": "Skill management and grants" },
|
|
{ "name": "MCP Servers", "description": "MCP server configuration and grants" },
|
|
{ "name": "Custom Tools", "description": "Custom tool definitions" },
|
|
{ "name": "Built-in Tools", "description": "Built-in tool configuration" },
|
|
{ "name": "Browser", "description": "Browser automation cookie sync" },
|
|
{ "name": "Memory", "description": "Agent memory (pgvector) management" },
|
|
{ "name": "Knowledge Graph", "description": "Entity knowledge graph" },
|
|
{ "name": "Channels", "description": "Channel instance management" },
|
|
{ "name": "Traces", "description": "LLM call tracing" },
|
|
{ "name": "Usage", "description": "Usage analytics" },
|
|
{ "name": "Activity", "description": "Audit activity log" },
|
|
{ "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": {
|
|
"/health": {
|
|
"get": {
|
|
"tags": ["System"],
|
|
"summary": "Health check",
|
|
"security": [],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Server health status",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"status": { "type": "string", "example": "ok" },
|
|
"uptime_ms": { "type": "integer" },
|
|
"mode": { "type": "string", "example": "managed" },
|
|
"database": { "type": "string", "example": "ok" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/browser/cookies/sync": {
|
|
"post": {
|
|
"tags": ["Browser"],
|
|
"summary": "Sync selected browser cookies",
|
|
"description": "Stores explicitly selected cookies for the authenticated user and one agent. Cookie values are encrypted at rest and are never returned by list APIs.",
|
|
"parameters": [
|
|
{ "name": "X-GoClaw-User-Id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Authenticated external user ID for cookie scope" }
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["agent_id", "cookies"],
|
|
"properties": {
|
|
"agent_id": { "type": "string" },
|
|
"source": { "type": "string", "example": "chrome-selected-cookie-sync" },
|
|
"cookies": {
|
|
"type": "array",
|
|
"maxItems": 200,
|
|
"items": {
|
|
"type": "object",
|
|
"required": ["name", "value"],
|
|
"properties": {
|
|
"domain": { "type": "string", "example": ".example.com" },
|
|
"url": { "type": "string", "example": "https://example.com/app" },
|
|
"name": { "type": "string" },
|
|
"path": { "type": "string", "example": "/" },
|
|
"value": { "type": "string" },
|
|
"secure": { "type": "boolean" },
|
|
"httpOnly": { "type": "boolean" },
|
|
"sameSite": { "type": "string" },
|
|
"expiresAt": { "type": "string", "format": "date-time" },
|
|
"expirationDate": { "type": "number", "description": "Unix seconds as returned by chrome.cookies" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": { "description": "Cookies synced", "content": { "application/json": { "schema": { "type": "object", "properties": { "synced": { "type": "integer" } } } } } },
|
|
"400": { "$ref": "#/components/responses/BadRequest" },
|
|
"503": { "description": "Cookie encryption is not configured" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/browser/cookies": {
|
|
"get": {
|
|
"tags": ["Browser"],
|
|
"summary": "List synced browser cookie metadata",
|
|
"description": "Lists metadata for cookies scoped to the authenticated user and requested agent. Cookie values are redacted.",
|
|
"parameters": [
|
|
{ "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" } },
|
|
{ "name": "domain", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "name", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "path", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "X-GoClaw-User-Id", "in": "header", "required": true, "schema": { "type": "string" } }
|
|
],
|
|
"responses": {
|
|
"200": { "description": "Cookie metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "secure": { "type": "boolean" }, "httpOnly": { "type": "boolean" }, "sameSite": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } },
|
|
"400": { "$ref": "#/components/responses/BadRequest" },
|
|
"503": { "description": "Cookie encryption is not configured" }
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": ["Browser"],
|
|
"summary": "Delete synced browser cookies",
|
|
"parameters": [
|
|
{ "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" } },
|
|
{ "name": "domain", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "name", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "path", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "X-GoClaw-User-Id", "in": "header", "required": true, "schema": { "type": "string" } }
|
|
],
|
|
"responses": {
|
|
"200": { "description": "Cookies deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer" } } } } } },
|
|
"400": { "$ref": "#/components/responses/BadRequest" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/chat/completions": {
|
|
"post": {
|
|
"tags": ["Chat"],
|
|
"summary": "OpenAI-compatible chat completions",
|
|
"description": "Send messages to an agent and get a response. Compatible with OpenAI's chat completions API.\n\nUse the `model` field to target a specific agent: `goclaw:<agent-id>` or `agent:<agent-id>`.",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["messages"],
|
|
"properties": {
|
|
"model": {
|
|
"type": "string",
|
|
"description": "Agent targeting: `goclaw:<id>` or `agent:<id>`. Defaults to `default`.",
|
|
"example": "goclaw:default"
|
|
},
|
|
"messages": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": ["role", "content"],
|
|
"properties": {
|
|
"role": { "type": "string", "enum": ["system", "user", "assistant"] },
|
|
"content": { "type": "string" }
|
|
}
|
|
}
|
|
},
|
|
"stream": { "type": "boolean", "default": false },
|
|
"user": { "type": "string", "description": "External user ID" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": { "description": "Chat completion response (or SSE stream if stream=true)" },
|
|
"401": { "$ref": "#/components/responses/Unauthorized" },
|
|
"429": { "description": "Rate limit exceeded" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/chat/sessions/{key}/branch": {
|
|
"post": {
|
|
"tags": ["Sessions"],
|
|
"summary": "Branch a chat session",
|
|
"parameters": [{ "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["up_to_index"],
|
|
"properties": {
|
|
"new_session_key": { "type": "string" },
|
|
"up_to_index": { "type": "integer", "minimum": 0 },
|
|
"label": { "type": "string" },
|
|
"metadata": { "type": "object", "additionalProperties": { "type": "string" } }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": { "description": "Session branched" },
|
|
"400": { "$ref": "#/components/responses/BadRequest" },
|
|
"403": { "$ref": "#/components/responses/Unauthorized" },
|
|
"404": { "$ref": "#/components/responses/NotFound" },
|
|
"409": { "$ref": "#/components/responses/Conflict" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/chat/sessions/{key}/history/follow": {
|
|
"get": {
|
|
"tags": ["Sessions"],
|
|
"summary": "Poll chat session history by index cursor",
|
|
"parameters": [
|
|
{ "name": "key", "in": "path", "required": true, "schema": { "type": "string" } },
|
|
{ "name": "cursor", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } },
|
|
{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }
|
|
],
|
|
"responses": {
|
|
"200": { "description": "History page" },
|
|
"400": { "$ref": "#/components/responses/BadRequest" },
|
|
"403": { "$ref": "#/components/responses/Unauthorized" },
|
|
"404": { "$ref": "#/components/responses/NotFound" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/api-keys": {
|
|
"get": {
|
|
"tags": ["API Keys"],
|
|
"summary": "List all API keys",
|
|
"description": "Returns all API keys (active and revoked). Key hashes are never included in responses. Requires admin access.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of API keys",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "array",
|
|
"items": { "$ref": "#/components/schemas/ApiKey" }
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": { "$ref": "#/components/responses/Unauthorized" }
|
|
}
|
|
},
|
|
"post": {
|
|
"tags": ["API Keys"],
|
|
"summary": "Create a new API key",
|
|
"description": "Creates a new API key with the specified scopes. The raw key is returned **only once** in the response — store it securely.\n\nAvailable scopes:\n- `operator.admin` — Full admin access\n- `operator.read` — Read-only access\n- `operator.write` — Read + write access\n- `operator.approvals` — Manage exec approvals\n- `operator.pairing` — Manage device pairing",
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["name", "scopes"],
|
|
"properties": {
|
|
"name": { "type": "string", "example": "ci-deploy" },
|
|
"scopes": {
|
|
"type": "array",
|
|
"items": { "type": "string", "enum": ["operator.admin", "operator.read", "operator.write", "operator.approvals", "operator.pairing"] },
|
|
"example": ["operator.read", "operator.write"]
|
|
},
|
|
"expires_in": {
|
|
"type": "integer",
|
|
"description": "Expiry in seconds. Omit or 0 for never.",
|
|
"example": 2592000
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "API key created. The `key` field is shown only once.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": { "type": "string", "format": "uuid" },
|
|
"name": { "type": "string" },
|
|
"prefix": { "type": "string", "example": "goclaw_a" },
|
|
"key": { "type": "string", "description": "Raw API key (shown once)", "example": "goclaw_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" },
|
|
"scopes": { "type": "array", "items": { "type": "string" } },
|
|
"expires_at": { "type": "string", "format": "date-time", "nullable": true },
|
|
"created_at": { "type": "string", "format": "date-time" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": { "$ref": "#/components/responses/BadRequest" },
|
|
"401": { "$ref": "#/components/responses/Unauthorized" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/auth/chatgpt/{provider}/quota": {
|
|
"get": {
|
|
"tags": ["OAuth"],
|
|
"summary": "Fetch OpenAI Codex OAuth quota for a provider",
|
|
"description": "Returns structured Codex/OpenAI quota state for a specific OpenAI Codex OAuth (`chatgpt_oauth`) provider. Missing provider returns `404`, provider type conflicts return `409`, and upstream quota problems return `200` with `success=false` so dashboards can render inline action states.",
|
|
"parameters": [
|
|
{
|
|
"name": "provider",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": { "type": "string" },
|
|
"description": "Provider alias (for example `openai-codex` or `codex-work`)."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Provider quota payload",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["provider_name", "success", "windows", "last_updated"],
|
|
"properties": {
|
|
"provider_name": { "type": "string", "example": "openai-codex" },
|
|
"success": { "type": "boolean" },
|
|
"plan_type": { "type": "string", "nullable": true, "example": "team" },
|
|
"windows": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"label": { "type": "string", "example": "Primary" },
|
|
"used_percent": { "type": "integer", "example": 24 },
|
|
"remaining_percent": { "type": "integer", "example": 76 },
|
|
"reset_after_seconds": { "type": "integer", "nullable": true, "example": 3600 },
|
|
"reset_at": { "type": "string", "format": "date-time", "nullable": true }
|
|
}
|
|
}
|
|
},
|
|
"core_usage": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"properties": {
|
|
"five_hour": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"properties": {
|
|
"label": { "type": "string" },
|
|
"remaining_percent": { "type": "integer" },
|
|
"reset_after_seconds": { "type": "integer", "nullable": true },
|
|
"reset_at": { "type": "string", "format": "date-time", "nullable": true }
|
|
}
|
|
},
|
|
"weekly": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"properties": {
|
|
"label": { "type": "string" },
|
|
"remaining_percent": { "type": "integer" },
|
|
"reset_after_seconds": { "type": "integer", "nullable": true },
|
|
"reset_at": { "type": "string", "format": "date-time", "nullable": true }
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"last_updated": { "type": "string", "format": "date-time" },
|
|
"error": { "type": "string" },
|
|
"error_code": { "type": "string" },
|
|
"action_hint": { "type": "string" },
|
|
"needs_reauth": { "type": "boolean" },
|
|
"is_forbidden": { "type": "boolean" },
|
|
"retryable": { "type": "boolean" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": { "$ref": "#/components/responses/BadRequest" },
|
|
"401": { "$ref": "#/components/responses/Unauthorized" },
|
|
"404": { "$ref": "#/components/responses/NotFound" },
|
|
"409": { "$ref": "#/components/responses/Conflict" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/auth/openai/quota": {
|
|
"get": {
|
|
"tags": ["OAuth"],
|
|
"summary": "Fetch quota for the default OpenAI Codex OAuth provider",
|
|
"description": "Compatibility alias for `/v1/auth/chatgpt/openai-codex/quota`.",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Provider quota payload",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/paths/~1v1~1auth~1chatgpt~1{provider}~1quota/get/responses/200/content/application~1json/schema"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": { "$ref": "#/components/responses/Unauthorized" },
|
|
"404": { "$ref": "#/components/responses/NotFound" },
|
|
"409": { "$ref": "#/components/responses/Conflict" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/agents": {
|
|
"get": {
|
|
"tags": ["Agents"],
|
|
"summary": "List agents",
|
|
"description": "List all agents accessible to the current user. Owners see all agents.",
|
|
"parameters": [
|
|
{ "name": "X-GoClaw-User-Id", "in": "header", "required": true, "schema": { "type": "string" } }
|
|
],
|
|
"responses": {
|
|
"200": { "description": "Agent list" },
|
|
"401": { "$ref": "#/components/responses/Unauthorized" }
|
|
}
|
|
},
|
|
"post": {
|
|
"tags": ["Agents"],
|
|
"summary": "Create agent",
|
|
"description": "Create a new agent with the specified configuration.",
|
|
"requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInput" } } } },
|
|
"responses": {
|
|
"201": { "description": "Agent created" },
|
|
"400": { "$ref": "#/components/responses/BadRequest" },
|
|
"401": { "$ref": "#/components/responses/Unauthorized" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/agents/{id}": {
|
|
"get": {
|
|
"tags": ["Agents"],
|
|
"summary": "Get agent",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Agent details" }, "404": { "$ref": "#/components/responses/NotFound" } }
|
|
},
|
|
"put": {
|
|
"tags": ["Agents"],
|
|
"summary": "Update agent",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInput" } } } },
|
|
"responses": { "200": { "description": "Agent updated" }, "404": { "$ref": "#/components/responses/NotFound" } }
|
|
},
|
|
"delete": {
|
|
"tags": ["Agents"],
|
|
"summary": "Delete agent",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Agent deleted" }, "404": { "$ref": "#/components/responses/NotFound" } }
|
|
}
|
|
},
|
|
"/v1/agents/{id}/codex-pool-activity": {
|
|
"get": {
|
|
"tags": ["Agents"],
|
|
"summary": "Summarize recent OpenAI Codex OAuth pool activity for an agent",
|
|
"description": "Returns explicit router-backed evidence for recent OpenAI Codex OAuth calls in the configured provider pool. Direct router selections are reported separately from failover serves, and each recent request shows both the selected alias and the alias that actually served the call.",
|
|
"parameters": [
|
|
{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": { "type": "integer", "default": 18, "minimum": 1, "maximum": 50 },
|
|
"description": "Maximum number of recent routed Codex LLM calls to include."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Codex pool activity payload",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["strategy", "pool_providers", "stats_sample_size", "provider_counts", "recent_requests"],
|
|
"properties": {
|
|
"strategy": { "type": "string", "enum": ["round_robin", "priority_order"] },
|
|
"pool_providers": {
|
|
"type": "array",
|
|
"items": { "type": "string" }
|
|
},
|
|
"stats_sample_size": {
|
|
"type": "integer",
|
|
"description": "Number of recent routed llm_call spans used to derive runtime health. The server samples max(limit, 120) spans even when recent_requests remains capped by limit."
|
|
},
|
|
"provider_counts": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": ["provider_name", "request_count", "direct_selection_count", "failover_serve_count", "success_count", "failure_count", "consecutive_failures", "success_rate", "health_score", "health_state"],
|
|
"properties": {
|
|
"provider_name": { "type": "string", "description": "Provider alias in the configured pool." },
|
|
"request_count": { "type": "integer", "description": "Backward-compatible count of requests where this alias was directly selected by the router." },
|
|
"direct_selection_count": { "type": "integer", "description": "Number of recent requests where the router selected this alias first." },
|
|
"failover_serve_count": { "type": "integer", "description": "Number of recent requests this alias served after another alias was selected first." },
|
|
"success_count": { "type": "integer", "description": "Trace-backed successes attributed to the alias that actually served the request." },
|
|
"failure_count": { "type": "integer", "description": "Trace-backed failures attributed to earlier attempted aliases on successful failover, or to every attempted alias on terminal error." },
|
|
"consecutive_failures": { "type": "integer", "description": "Newest-first failure streak for this alias." },
|
|
"success_rate": { "type": "integer", "description": "Success rate percent derived from recent runtime outcomes." },
|
|
"health_score": { "type": "integer", "description": "Heuristic runtime health score from 0 to 100." },
|
|
"health_state": { "type": "string", "description": "Health band derived from recent runtime outcomes: idle when there are no outcomes, critical at 3+ consecutive failures or score < 40, degraded below 80, otherwise healthy.", "enum": ["idle", "healthy", "degraded", "critical"] },
|
|
"last_selected_at": { "type": "string", "format": "date-time", "nullable": true },
|
|
"last_failover_at": { "type": "string", "format": "date-time", "nullable": true },
|
|
"last_used_at": { "type": "string", "format": "date-time", "nullable": true },
|
|
"last_success_at": { "type": "string", "format": "date-time", "nullable": true },
|
|
"last_failure_at": { "type": "string", "format": "date-time", "nullable": true }
|
|
}
|
|
}
|
|
},
|
|
"recent_requests": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": ["span_id", "trace_id", "started_at", "status", "duration_ms", "provider_name", "model", "attempt_count", "used_failover"],
|
|
"properties": {
|
|
"span_id": { "type": "string", "format": "uuid" },
|
|
"trace_id": { "type": "string", "format": "uuid" },
|
|
"started_at": { "type": "string", "format": "date-time" },
|
|
"status": { "type": "string" },
|
|
"duration_ms": { "type": "integer" },
|
|
"provider_name": { "type": "string", "description": "Alias that actually served the request. Empty when a terminal failure completed without any alias serving successfully." },
|
|
"selected_provider": { "type": "string", "description": "Alias chosen first by the router before any failover." },
|
|
"model": { "type": "string" },
|
|
"attempt_count": { "type": "integer" },
|
|
"used_failover": { "type": "boolean" },
|
|
"failover_providers": {
|
|
"type": "array",
|
|
"items": { "type": "string" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": { "$ref": "#/components/responses/Unauthorized" },
|
|
"404": { "$ref": "#/components/responses/NotFound" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/agents/{id}/wake": {
|
|
"post": {
|
|
"tags": ["Agents"],
|
|
"summary": "Wake/trigger agent externally",
|
|
"description": "Trigger an agent run from an external webhook or automation.",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "user_id": { "type": "string" } } } } } },
|
|
"responses": { "200": { "description": "Agent triggered" } }
|
|
}
|
|
},
|
|
"/v1/providers": {
|
|
"get": {
|
|
"tags": ["Providers"],
|
|
"summary": "List LLM providers",
|
|
"responses": { "200": { "description": "Provider list (API keys masked)" } }
|
|
},
|
|
"post": {
|
|
"tags": ["Providers"],
|
|
"summary": "Create LLM provider",
|
|
"requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderInput" } } } },
|
|
"responses": { "201": { "description": "Provider created" } }
|
|
}
|
|
},
|
|
"/v1/providers/{id}": {
|
|
"get": {
|
|
"tags": ["Providers"],
|
|
"summary": "Get provider",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Provider details (API key masked)" } }
|
|
},
|
|
"put": {
|
|
"tags": ["Providers"],
|
|
"summary": "Update provider",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Provider updated" } }
|
|
},
|
|
"delete": {
|
|
"tags": ["Providers"],
|
|
"summary": "Delete provider",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Provider deleted" } }
|
|
}
|
|
},
|
|
"/v1/providers/{id}/reconnect": {
|
|
"post": {
|
|
"tags": ["Providers"],
|
|
"summary": "Reconnect provider runtime",
|
|
"description": "Reload an existing provider from stored config into the runtime registry. Does not mutate stored config and does not call upstream verification.",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"requestBody": {
|
|
"required": false,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"verify": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "Only false is supported. Call /v1/providers/{id}/verify separately for upstream verification."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Provider reconnect result",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"status": { "type": "string", "enum": ["reconnected", "disabled", "not_registered"] },
|
|
"provider": { "$ref": "#/components/schemas/ProviderInput" },
|
|
"registry_updated": { "type": "boolean" },
|
|
"cache_invalidated": { "type": "boolean" }
|
|
},
|
|
"required": ["status", "provider", "registry_updated", "cache_invalidated"]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": { "$ref": "#/components/responses/BadRequest" },
|
|
"404": { "$ref": "#/components/responses/NotFound" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/providers/{id}/models": {
|
|
"get": {
|
|
"tags": ["Providers"],
|
|
"summary": "List available models",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Model list with optional reasoning capability metadata",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"models": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": { "type": "string" },
|
|
"name": { "type": "string" },
|
|
"reasoning": {
|
|
"type": "object",
|
|
"properties": {
|
|
"levels": {
|
|
"type": "array",
|
|
"items": { "type": "string" }
|
|
},
|
|
"default_effort": { "type": "string" }
|
|
}
|
|
}
|
|
},
|
|
"required": ["id"]
|
|
}
|
|
},
|
|
"reasoning_defaults": {
|
|
"type": "object",
|
|
"description": "Provider-owned default reasoning policy returned when the provider has saved defaults and at least one discovered model exposes reasoning capability metadata.",
|
|
"properties": {
|
|
"effort": {
|
|
"type": "string",
|
|
"enum": ["off", "auto", "none", "minimal", "low", "medium", "high", "xhigh"]
|
|
},
|
|
"fallback": {
|
|
"type": "string",
|
|
"enum": ["downgrade", "off", "provider_default"]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"required": ["models"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/providers/{id}/verify": {
|
|
"post": {
|
|
"tags": ["Providers"],
|
|
"summary": "Verify provider connection",
|
|
"description": "Empty body or omitted model = ping mode (provider registered/reachable check). With model = full chat-verify against the upstream provider.",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Optional. Omit (or send empty body) for ping mode." } } } } } },
|
|
"responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "error": { "type": "string" } } } } } } }
|
|
}
|
|
},
|
|
"/v1/skills": {
|
|
"get": {
|
|
"tags": ["Skills"],
|
|
"summary": "List all skills",
|
|
"responses": { "200": { "description": "Skill list" } }
|
|
},
|
|
"post": {
|
|
"tags": ["Skills"],
|
|
"summary": "Upload skill",
|
|
"requestBody": { "content": { "multipart/form-data": {} } },
|
|
"responses": { "201": { "description": "Skill uploaded" } }
|
|
}
|
|
},
|
|
"/v1/skills/{id}": {
|
|
"get": {
|
|
"tags": ["Skills"],
|
|
"summary": "Get skill",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Skill details" } }
|
|
},
|
|
"put": {
|
|
"tags": ["Skills"],
|
|
"summary": "Update skill",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Skill updated" } }
|
|
},
|
|
"delete": {
|
|
"tags": ["Skills"],
|
|
"summary": "Delete skill",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Skill deleted" } }
|
|
}
|
|
},
|
|
"/v1/tools/custom": {
|
|
"get": {
|
|
"tags": ["Custom Tools"],
|
|
"summary": "List custom tools",
|
|
"responses": { "200": { "description": "Custom tool list" } }
|
|
},
|
|
"post": {
|
|
"tags": ["Custom Tools"],
|
|
"summary": "Create custom tool",
|
|
"responses": { "201": { "description": "Tool created" } }
|
|
}
|
|
},
|
|
"/v1/tools/custom/{id}": {
|
|
"get": {
|
|
"tags": ["Custom Tools"],
|
|
"summary": "Get custom tool",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Tool details" } }
|
|
},
|
|
"put": {
|
|
"tags": ["Custom Tools"],
|
|
"summary": "Update custom tool",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Tool updated" } }
|
|
},
|
|
"delete": {
|
|
"tags": ["Custom Tools"],
|
|
"summary": "Delete custom tool",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Tool deleted" } }
|
|
}
|
|
},
|
|
"/v1/tools/builtin": {
|
|
"get": {
|
|
"tags": ["Built-in Tools"],
|
|
"summary": "List built-in tools",
|
|
"responses": { "200": { "description": "Built-in tool list" } }
|
|
}
|
|
},
|
|
"/v1/tools/builtin/{name}": {
|
|
"get": {
|
|
"tags": ["Built-in Tools"],
|
|
"summary": "Get built-in tool",
|
|
"parameters": [{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Tool details" } }
|
|
},
|
|
"put": {
|
|
"tags": ["Built-in Tools"],
|
|
"summary": "Update tool settings",
|
|
"parameters": [{ "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Tool updated" } }
|
|
}
|
|
},
|
|
"/v1/mcp/servers": {
|
|
"get": {
|
|
"tags": ["MCP Servers"],
|
|
"summary": "List MCP servers",
|
|
"responses": { "200": { "description": "MCP server list" } }
|
|
},
|
|
"post": {
|
|
"tags": ["MCP Servers"],
|
|
"summary": "Create MCP server",
|
|
"responses": { "201": { "description": "Server created" } }
|
|
}
|
|
},
|
|
"/v1/mcp/servers/{id}": {
|
|
"get": {
|
|
"tags": ["MCP Servers"],
|
|
"summary": "Get MCP server",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Server details" } }
|
|
},
|
|
"put": {
|
|
"tags": ["MCP Servers"],
|
|
"summary": "Update MCP server",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Server updated" } }
|
|
},
|
|
"delete": {
|
|
"tags": ["MCP Servers"],
|
|
"summary": "Delete MCP server",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Server deleted" } }
|
|
}
|
|
},
|
|
"/v1/mcp/servers/{id}/tools": {
|
|
"get": {
|
|
"tags": ["MCP Servers"],
|
|
"summary": "List server tools",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Tool list" } }
|
|
}
|
|
},
|
|
"/v1/memory/documents": {
|
|
"get": {
|
|
"tags": ["Memory"],
|
|
"summary": "List all memory documents",
|
|
"responses": { "200": { "description": "Document list" } }
|
|
}
|
|
},
|
|
"/v1/agents/{agentID}/memory/search": {
|
|
"post": {
|
|
"tags": ["Memory"],
|
|
"summary": "Search agent memory",
|
|
"parameters": [{ "name": "agentID", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "limit": { "type": "integer", "default": 10 } } } } } },
|
|
"responses": { "200": { "description": "Search results" } }
|
|
}
|
|
},
|
|
"/v1/agents/{agentID}/kg/entities": {
|
|
"get": {
|
|
"tags": ["Knowledge Graph"],
|
|
"summary": "List KG entities",
|
|
"parameters": [{ "name": "agentID", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Entity list" } }
|
|
},
|
|
"post": {
|
|
"tags": ["Knowledge Graph"],
|
|
"summary": "Upsert KG entity",
|
|
"parameters": [{ "name": "agentID", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Entity upserted" } }
|
|
}
|
|
},
|
|
"/v1/agents/{agentID}/kg/traverse": {
|
|
"post": {
|
|
"tags": ["Knowledge Graph"],
|
|
"summary": "Traverse knowledge graph",
|
|
"parameters": [{ "name": "agentID", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Traversal results" } }
|
|
}
|
|
},
|
|
"/v1/channels/instances": {
|
|
"get": {
|
|
"tags": ["Channels"],
|
|
"summary": "List channel instances",
|
|
"responses": { "200": { "description": "Instance list" } }
|
|
},
|
|
"post": {
|
|
"tags": ["Channels"],
|
|
"summary": "Create channel instance",
|
|
"responses": { "201": { "description": "Instance created" } }
|
|
}
|
|
},
|
|
"/v1/channels/instances/{id}": {
|
|
"get": {
|
|
"tags": ["Channels"],
|
|
"summary": "Get channel instance",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Instance details" } }
|
|
},
|
|
"put": {
|
|
"tags": ["Channels"],
|
|
"summary": "Update channel instance",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Instance updated" } }
|
|
},
|
|
"delete": {
|
|
"tags": ["Channels"],
|
|
"summary": "Delete channel instance",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"responses": { "200": { "description": "Instance deleted" } }
|
|
}
|
|
},
|
|
"/v1/channels/instances/{id}/writers/test": {
|
|
"post": {
|
|
"tags": ["Channels"],
|
|
"summary": "Test channel group writer permission",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["group_id", "user_id"],
|
|
"properties": {
|
|
"group_id": { "type": "string", "example": "group:telegram:-100123" },
|
|
"user_id": { "type": "string", "example": "386246614" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": { "description": "Writer permission decision" },
|
|
"400": { "$ref": "#/components/responses/BadRequest" },
|
|
"404": { "$ref": "#/components/responses/NotFound" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/contacts": {
|
|
"get": {
|
|
"tags": ["Channels"],
|
|
"summary": "List channel contacts",
|
|
"responses": { "200": { "description": "Contact list" } }
|
|
}
|
|
},
|
|
"/v1/traces": {
|
|
"get": {
|
|
"tags": ["Traces"],
|
|
"summary": "List LLM traces",
|
|
"parameters": [
|
|
{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } },
|
|
{ "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } },
|
|
{ "name": "agent_id", "in": "query", "schema": { "type": "string" } }
|
|
],
|
|
"responses": { "200": { "description": "Trace list" } }
|
|
}
|
|
},
|
|
"/v1/traces/follow": {
|
|
"get": {
|
|
"tags": ["Traces"],
|
|
"summary": "Poll trace changes",
|
|
"description": "Stateless polling endpoint for traces in one session or one agent. Requires session_key or agent_id.",
|
|
"parameters": [
|
|
{ "name": "session_key", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "agent_id", "in": "query", "schema": { "type": "string", "format": "uuid" } },
|
|
{ "name": "status", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "channel", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } },
|
|
{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } },
|
|
{ "name": "include_spans", "in": "query", "schema": { "type": "boolean", "default": false } }
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Trace follow page",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"traces": { "type": "array", "items": { "type": "object" } },
|
|
"spans_by_trace_id": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object" } } },
|
|
"server_time": { "type": "string", "format": "date-time" },
|
|
"next_since": { "type": "string", "format": "date-time" },
|
|
"limit": { "type": "integer" }
|
|
},
|
|
"required": ["traces", "spans_by_trace_id", "server_time", "next_since", "limit"]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": { "$ref": "#/components/responses/BadRequest" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/traces/{traceID}": {
|
|
"get": {
|
|
"tags": ["Traces"],
|
|
"summary": "Get trace detail",
|
|
"parameters": [{ "name": "traceID", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Trace detail with messages" } }
|
|
}
|
|
},
|
|
"/v1/costs/summary": {
|
|
"get": {
|
|
"tags": ["Traces"],
|
|
"summary": "Get cost summary",
|
|
"responses": { "200": { "description": "Cost summary" } }
|
|
}
|
|
},
|
|
"/v1/usage/timeseries": {
|
|
"get": {
|
|
"tags": ["Usage"],
|
|
"summary": "Usage timeseries analytics",
|
|
"parameters": [
|
|
{ "name": "period", "in": "query", "schema": { "type": "string", "enum": ["1h", "24h", "7d", "30d"] } }
|
|
],
|
|
"responses": { "200": { "description": "Timeseries data" } }
|
|
}
|
|
},
|
|
"/v1/usage/summary": {
|
|
"get": {
|
|
"tags": ["Usage"],
|
|
"summary": "Usage summary",
|
|
"responses": { "200": { "description": "Usage summary" } }
|
|
}
|
|
},
|
|
"/v1/activity": {
|
|
"get": {
|
|
"tags": ["Activity"],
|
|
"summary": "List audit activity logs",
|
|
"parameters": [
|
|
{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } },
|
|
{ "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
|
|
],
|
|
"responses": { "200": { "description": "Activity log entries" } }
|
|
}
|
|
},
|
|
"/v1/activity/aggregate": {
|
|
"get": {
|
|
"tags": ["Activity"],
|
|
"summary": "Aggregate audit activity logs",
|
|
"parameters": [
|
|
{ "name": "group_by", "in": "query", "required": true, "schema": { "type": "string", "enum": ["action", "actor_type", "entity_type", "actor_id"] } },
|
|
{ "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } },
|
|
{ "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } },
|
|
{ "name": "actor_type", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "actor_id", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "action", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "entity_type", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "entity_id", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }
|
|
],
|
|
"responses": {
|
|
"200": { "description": "Activity aggregate buckets" },
|
|
"400": { "$ref": "#/components/responses/BadRequest" },
|
|
"403": { "$ref": "#/components/responses/Unauthorized" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/logs/runtime/aggregate": {
|
|
"get": {
|
|
"tags": ["Activity"],
|
|
"summary": "Aggregate recent runtime logs from the in-memory ring buffer",
|
|
"parameters": [
|
|
{ "name": "group_by", "in": "query", "schema": { "type": "string", "enum": ["level", "source"], "default": "level" } },
|
|
{ "name": "level", "in": "query", "schema": { "type": "string", "enum": ["debug", "info", "warn", "error"] } },
|
|
{ "name": "source", "in": "query", "schema": { "type": "string" } },
|
|
{ "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }
|
|
],
|
|
"responses": {
|
|
"200": { "description": "Runtime log aggregate buckets" },
|
|
"400": { "$ref": "#/components/responses/BadRequest" },
|
|
"403": { "$ref": "#/components/responses/Unauthorized" },
|
|
"503": { "description": "Runtime log tee unavailable" }
|
|
}
|
|
}
|
|
},
|
|
"/v1/delegations": {
|
|
"get": {
|
|
"tags": ["Activity"],
|
|
"summary": "List delegation history",
|
|
"responses": { "200": { "description": "Delegation list" } }
|
|
}
|
|
},
|
|
"/v1/storage/files": {
|
|
"get": {
|
|
"tags": ["Storage"],
|
|
"summary": "List workspace files",
|
|
"parameters": [
|
|
{ "name": "path", "in": "query", "schema": { "type": "string" }, "description": "Subdirectory path" }
|
|
],
|
|
"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": {
|
|
"tags": ["Media"],
|
|
"summary": "Upload media file",
|
|
"requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } },
|
|
"responses": { "200": { "description": "Upload result with temp path and MIME type" } }
|
|
}
|
|
},
|
|
"/v1/media/{id}": {
|
|
"get": {
|
|
"tags": ["Media"],
|
|
"summary": "Serve media by ID",
|
|
"parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
|
|
"responses": { "200": { "description": "Media file" } }
|
|
}
|
|
},
|
|
"/v1/pending-messages": {
|
|
"get": {
|
|
"tags": ["Channels"],
|
|
"summary": "List pending message groups",
|
|
"responses": { "200": { "description": "Message group list" } }
|
|
},
|
|
"delete": {
|
|
"tags": ["Channels"],
|
|
"summary": "Clear pending message group",
|
|
"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",
|
|
"provider_model",
|
|
"channel"
|
|
]
|
|
}
|
|
}
|
|
],
|
|
"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": {
|
|
"bearerAuth": {
|
|
"type": "http",
|
|
"scheme": "bearer",
|
|
"description": "Gateway token or API key"
|
|
}
|
|
},
|
|
"schemas": {
|
|
"ApiKey": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": { "type": "string", "format": "uuid" },
|
|
"name": { "type": "string" },
|
|
"prefix": { "type": "string", "description": "First 8 chars for identification" },
|
|
"scopes": { "type": "array", "items": { "type": "string" } },
|
|
"expires_at": { "type": "string", "format": "date-time", "nullable": true },
|
|
"last_used_at": { "type": "string", "format": "date-time", "nullable": true },
|
|
"revoked": { "type": "boolean" },
|
|
"created_by": { "type": "string" },
|
|
"created_at": { "type": "string", "format": "date-time" },
|
|
"updated_at": { "type": "string", "format": "date-time" }
|
|
}
|
|
},
|
|
"AgentInput": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": { "type": "string", "description": "Unique agent slug" },
|
|
"display_name": { "type": "string" },
|
|
"agent_type": { "type": "string", "enum": ["open", "predefined"] },
|
|
"description": { "type": "string" },
|
|
"provider": { "type": "string", "description": "LLM provider name" },
|
|
"model": { "type": "string", "description": "Model ID" },
|
|
"system_prompt": { "type": "string" },
|
|
"other_config": {
|
|
"type": "object",
|
|
"description": "Optional legacy/extensibility bag. Do not nest reasoning or Codex routing here in new writes."
|
|
},
|
|
"reasoning_config": {
|
|
"type": "object",
|
|
"description": "Capability-aware reasoning policy for GPT-5/Codex models.",
|
|
"properties": {
|
|
"override_mode": {
|
|
"type": "string",
|
|
"enum": ["inherit", "custom"]
|
|
},
|
|
"effort": {
|
|
"type": "string",
|
|
"enum": ["off", "auto", "none", "minimal", "low", "medium", "high", "xhigh"]
|
|
},
|
|
"fallback": {
|
|
"type": "string",
|
|
"enum": ["downgrade", "off", "provider_default"]
|
|
}
|
|
}
|
|
},
|
|
"chatgpt_oauth_routing": {
|
|
"type": "object",
|
|
"description": "Optional agent-side routing override for ChatGPT OAuth providers. The main provider field remains the preferred/default account, while provider settings may supply inherited defaults.",
|
|
"properties": {
|
|
"override_mode": { "type": "string", "enum": ["inherit", "custom"] },
|
|
"strategy": { "type": "string", "enum": ["round_robin", "priority_order"] },
|
|
"extra_provider_names": { "type": "array", "items": { "type": "string" } }
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ProviderInput": {
|
|
"type": "object",
|
|
"required": ["name", "provider_type"],
|
|
"properties": {
|
|
"name": { "type": "string", "description": "Unique provider slug" },
|
|
"display_name": { "type": "string" },
|
|
"provider_type": { "type": "string", "enum": ["aimlapi", "anthropic_native", "openai_compat", "gemini_native", "openrouter", "groq", "deepseek", "mistral", "xai", "minimax_native", "cohere", "perplexity", "dashscope", "bailian", "chatgpt_oauth", "claude_cli", "yescale", "zai", "zai_coding", "ollama", "ollama_cloud", "acp"] },
|
|
"api_base": { "type": "string" },
|
|
"api_key": { "type": "string" },
|
|
"enabled": { "type": "boolean", "default": true },
|
|
"settings": {
|
|
"type": "object",
|
|
"description": "Provider-specific settings such as provider-owned Codex pool defaults and reasoning defaults.",
|
|
"properties": {
|
|
"reasoning_defaults": {
|
|
"type": "object",
|
|
"properties": {
|
|
"effort": {
|
|
"type": "string",
|
|
"enum": ["off", "auto", "none", "minimal", "low", "medium", "high", "xhigh"]
|
|
},
|
|
"fallback": {
|
|
"type": "string",
|
|
"enum": ["downgrade", "off", "provider_default"]
|
|
}
|
|
}
|
|
},
|
|
"codex_pool": {
|
|
"type": "object",
|
|
"properties": {
|
|
"strategy": {
|
|
"type": "string",
|
|
"enum": ["round_robin", "priority_order"]
|
|
},
|
|
"extra_provider_names": {
|
|
"type": "array",
|
|
"items": { "type": "string" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Error": {
|
|
"type": "object",
|
|
"properties": {
|
|
"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",
|
|
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
|
|
},
|
|
"BadRequest": {
|
|
"description": "Invalid request parameters",
|
|
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
|
|
},
|
|
"NotFound": {
|
|
"description": "Resource not found",
|
|
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
|
|
},
|
|
"Conflict": {
|
|
"description": "Resource state conflict",
|
|
"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
|
|
}
|
|
}
|
|
}
|
|
}
|