{ "openapi": "3.1.0", "info": { "title": "nexu Controller API", "version": "1.0.0" }, "components": { "schemas": {}, "parameters": {} }, "paths": { "/api/v1/bots": { "get": { "tags": [ "Bots" ], "responses": { "200": { "description": "Bot list", "content": { "application/json": { "schema": { "type": "object", "properties": { "bots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "poolId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "modelId": { "type": "string" }, "systemPrompt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "slug", "poolId", "status", "modelId", "systemPrompt", "createdAt", "updatedAt" ] } } }, "required": [ "bots" ] } } } } } }, "post": { "tags": [ "Bots" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9-]+$" }, "systemPrompt": { "type": "string" }, "modelId": { "type": "string", "default": "gpt-4o" }, "poolId": { "type": "string" } }, "required": [ "name", "slug" ] } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "poolId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "modelId": { "type": "string" }, "systemPrompt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "slug", "poolId", "status", "modelId", "systemPrompt", "createdAt", "updatedAt" ] } } } } } } }, "/api/v1/bots/{botId}": { "get": { "tags": [ "Bots" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "botId", "in": "path" } ], "responses": { "200": { "description": "Bot", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "poolId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "modelId": { "type": "string" }, "systemPrompt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "slug", "poolId", "status", "modelId", "systemPrompt", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } }, "patch": { "tags": [ "Bots" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "botId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "systemPrompt": { "type": "string" }, "modelId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "poolId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "modelId": { "type": "string" }, "systemPrompt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "slug", "poolId", "status", "modelId", "systemPrompt", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } }, "delete": { "tags": [ "Bots" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "botId", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } } } }, "/api/v1/bots/{botId}/pause": { "post": { "tags": [ "Bots" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "botId", "in": "path" } ], "responses": { "200": { "description": "Paused", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "poolId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "modelId": { "type": "string" }, "systemPrompt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "slug", "poolId", "status", "modelId", "systemPrompt", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/bots/{botId}/resume": { "post": { "tags": [ "Bots" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "botId", "in": "path" } ], "responses": { "200": { "description": "Resumed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "poolId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "paused", "deleted" ] }, "modelId": { "type": "string" }, "systemPrompt": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "slug", "poolId", "status", "modelId", "systemPrompt", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/v1/chat/completions": { "post": { "tags": [ "Compat" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "nullable": true } } ] }, "name": { "type": "string" }, "tool_call_id": { "type": "string" } }, "required": [ "role", "content" ] } }, "stream": { "type": "boolean" }, "user": { "type": "string" } }, "required": [ "messages" ] } } } }, "responses": { "200": { "description": "OpenAI-compatible streaming chat completions", "content": { "text/event-stream": { "schema": { "type": "string" } } } } } } }, "/api/v1/auth/desktop-authorize": { "post": { "tags": [ "Auth" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceId": { "type": "string" } }, "required": [ "deviceId" ] } } } }, "responses": { "200": { "description": "Desktop authorize", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } } } } }, "/api/v1/invite/validate": { "post": { "tags": [ "Invite" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1 } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Invite validate", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "valid" ] } } } } } } }, "/api/v1/feishu/bind/oauth-url": { "get": { "tags": [ "Feishu" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "workspaceKey", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "botId", "in": "query" } ], "responses": { "200": { "description": "Feishu bind url", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } } } } }, "/api/shared-slack/resolve-claim-key": { "get": { "tags": [ "Shared Slack App" ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "token", "in": "query" } ], "responses": { "200": { "description": "Resolve claim", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "expired": { "type": "boolean" }, "used": { "type": "boolean" }, "teamId": { "type": "string" }, "teamName": { "type": "string", "nullable": true }, "imUserId": { "type": "string" }, "isExistingWorkspace": { "type": "boolean" }, "memberCount": { "type": "number" } }, "required": [ "valid", "expired", "used" ] } } } } } } }, "/api/v1/shared-slack/claim": { "post": { "tags": [ "Shared Slack App" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "Shared slack claim", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "orgAuthorized": { "type": "boolean" } }, "required": [ "ok", "orgAuthorized" ] } } } } } } }, "/api/internal/desktop/shell-open": { "post": { "tags": [ "Desktop" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 } }, "required": [ "path" ] } } } }, "responses": { "200": { "description": "Shell open result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } }, "403": { "description": "Path not allowed", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } } } } }, "/api/internal/desktop/ready": { "get": { "tags": [ "Desktop" ], "responses": { "200": { "description": "Desktop runtime ready status", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "workspacePath": { "type": "string" }, "runtime": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "number", "nullable": true } }, "required": [ "ok", "status" ] }, "status": { "type": "string", "enum": [ "active", "starting", "degraded", "unhealthy" ] } }, "required": [ "ready", "workspacePath", "runtime", "status" ] } } } } } } }, "/api/internal/desktop/fallback-events": { "get": { "tags": [ "Desktop" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Recent channel fallback diagnostics", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "receivedAt": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "reasonCode": { "type": "string", "nullable": true }, "accountId": { "type": "string", "nullable": true }, "to": { "type": "string", "nullable": true }, "threadId": { "type": "string", "nullable": true }, "sessionKey": { "type": "string", "nullable": true }, "actionId": { "type": "string", "nullable": true }, "fallbackOutcome": { "type": "string", "enum": [ "sent", "skipped", "failed" ] }, "fallbackReason": { "type": "string" }, "error": { "type": "string", "nullable": true }, "sendResult": { "type": "object", "nullable": true, "properties": { "runId": { "type": "string" }, "messageId": { "type": "string" }, "channel": { "type": "string" }, "chatId": { "type": "string" }, "conversationId": { "type": "string" } } } }, "required": [ "id", "receivedAt", "channel", "status", "reasonCode", "accountId", "to", "threadId", "sessionKey", "actionId", "fallbackOutcome", "fallbackReason", "error", "sendResult" ] } } }, "required": [ "events" ] } } } } } } }, "/api/internal/desktop/preferences": { "get": { "tags": [ "Desktop" ], "responses": { "200": { "description": "Desktop preferences", "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "nullable": true, "enum": [ "en", "zh-CN" ] } }, "required": [ "locale" ] } } } } } }, "patch": { "tags": [ "Desktop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "en", "zh-CN" ] } }, "required": [ "locale" ] } } } }, "responses": { "200": { "description": "Updated desktop preferences", "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "nullable": true, "enum": [ "en", "zh-CN" ] } }, "required": [ "locale" ] } } } } } } }, "/api/auth/get-session": { "get": { "tags": [ "Desktop" ], "responses": { "200": { "description": "Desktop-local auth session", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "id", "expiresAt" ] }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string", "nullable": true } }, "required": [ "id", "email", "name", "image" ] } }, "required": [ "session", "user" ] } } } } } } }, "/api/internal/desktop/cloud-status": { "get": { "tags": [ "Desktop" ], "responses": { "200": { "description": "Cloud status", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name" ] } }, "cloudUrl": { "type": "string" }, "linkUrl": { "type": "string", "nullable": true }, "activeProfileName": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" }, "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "modelCount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "cloudUrl", "linkUrl", "connected", "modelCount" ] } } }, "required": [ "connected", "cloudUrl", "linkUrl", "activeProfileName", "profiles" ] } } } } } } }, "/api/internal/desktop/cloud-connect": { "post": { "tags": [ "Desktop" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Cloud connect", "content": { "application/json": { "schema": { "type": "object", "properties": { "browserUrl": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "/api/internal/desktop/cloud-profile/connect": { "post": { "tags": [ "Desktop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Connect cloud profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "browserUrl": { "type": "string" }, "error": { "type": "string" }, "status": { "type": "object", "properties": { "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name" ] } }, "cloudUrl": { "type": "string" }, "linkUrl": { "type": "string", "nullable": true }, "activeProfileName": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" }, "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "modelCount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "cloudUrl", "linkUrl", "connected", "modelCount" ] } } }, "required": [ "connected", "cloudUrl", "linkUrl", "activeProfileName", "profiles" ] }, "configPushed": { "type": "boolean" } }, "required": [ "status", "configPushed" ] } } } } } } }, "/api/internal/desktop/cloud-refresh": { "post": { "tags": [ "Desktop" ], "responses": { "200": { "description": "Cloud refresh", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name" ] } }, "cloudUrl": { "type": "string" }, "linkUrl": { "type": "string", "nullable": true }, "activeProfileName": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" }, "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "modelCount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "cloudUrl", "linkUrl", "connected", "modelCount" ] } }, "configPushed": { "type": "boolean" } }, "required": [ "connected", "cloudUrl", "linkUrl", "activeProfileName", "profiles", "configPushed" ] } } } } } } }, "/api/internal/desktop/cloud-profile/create": { "post": { "tags": [ "Desktop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" } }, "required": [ "name", "cloudUrl", "linkUrl" ] } }, "required": [ "profile" ] } } } }, "responses": { "200": { "description": "Create cloud profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name" ] } }, "cloudUrl": { "type": "string" }, "linkUrl": { "type": "string", "nullable": true }, "activeProfileName": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" }, "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "modelCount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "cloudUrl", "linkUrl", "connected", "modelCount" ] } }, "ok": { "type": "boolean" }, "configPushed": { "type": "boolean" } }, "required": [ "connected", "cloudUrl", "linkUrl", "activeProfileName", "profiles", "ok", "configPushed" ] } } } } } } }, "/api/internal/desktop/cloud-profile/update": { "post": { "tags": [ "Desktop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "previousName": { "type": "string", "minLength": 1 }, "profile": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" } }, "required": [ "name", "cloudUrl", "linkUrl" ] } }, "required": [ "previousName", "profile" ] } } } }, "responses": { "200": { "description": "Update cloud profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name" ] } }, "cloudUrl": { "type": "string" }, "linkUrl": { "type": "string", "nullable": true }, "activeProfileName": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" }, "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "modelCount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "cloudUrl", "linkUrl", "connected", "modelCount" ] } }, "ok": { "type": "boolean" }, "configPushed": { "type": "boolean" } }, "required": [ "connected", "cloudUrl", "linkUrl", "activeProfileName", "profiles", "ok", "configPushed" ] } } } } } } }, "/api/internal/desktop/cloud-profile/delete": { "post": { "tags": [ "Desktop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Delete cloud profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name" ] } }, "cloudUrl": { "type": "string" }, "linkUrl": { "type": "string", "nullable": true }, "activeProfileName": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" }, "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "modelCount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "cloudUrl", "linkUrl", "connected", "modelCount" ] } }, "ok": { "type": "boolean" }, "configPushed": { "type": "boolean" } }, "required": [ "connected", "cloudUrl", "linkUrl", "activeProfileName", "profiles", "ok", "configPushed" ] } } } } } } }, "/api/internal/desktop/cloud-disconnect": { "post": { "tags": [ "Desktop" ], "responses": { "200": { "description": "Cloud disconnect", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } } } }, "/api/internal/desktop/cloud-profile/disconnect": { "post": { "tags": [ "Desktop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Disconnect cloud profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name" ] } }, "cloudUrl": { "type": "string" }, "linkUrl": { "type": "string", "nullable": true }, "activeProfileName": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" }, "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "modelCount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "cloudUrl", "linkUrl", "connected", "modelCount" ] } }, "ok": { "type": "boolean" }, "configPushed": { "type": "boolean" } }, "required": [ "connected", "cloudUrl", "linkUrl", "activeProfileName", "profiles", "ok", "configPushed" ] } } } } } } }, "/api/internal/desktop/cloud-profile/select": { "post": { "tags": [ "Desktop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Switch cloud profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name" ] } }, "cloudUrl": { "type": "string" }, "linkUrl": { "type": "string", "nullable": true }, "activeProfileName": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" }, "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "modelCount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "cloudUrl", "linkUrl", "connected", "modelCount" ] } }, "ok": { "type": "boolean" }, "configPushed": { "type": "boolean" } }, "required": [ "connected", "cloudUrl", "linkUrl", "activeProfileName", "profiles", "ok", "configPushed" ] } } } } } } }, "/api/internal/desktop/cloud-profiles/import": { "post": { "tags": [ "Desktop" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" } }, "required": [ "name", "cloudUrl", "linkUrl" ] } } }, "required": [ "profiles" ] } } } }, "responses": { "200": { "description": "Import cloud profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name" ] } }, "cloudUrl": { "type": "string" }, "linkUrl": { "type": "string", "nullable": true }, "activeProfileName": { "type": "string" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "cloudUrl": { "type": "string", "format": "uri" }, "linkUrl": { "type": "string", "format": "uri" }, "connected": { "type": "boolean" }, "polling": { "type": "boolean" }, "userId": { "type": "string", "nullable": true }, "userName": { "type": "string", "nullable": true }, "userEmail": { "type": "string", "nullable": true }, "connectedAt": { "type": "string", "nullable": true }, "modelCount": { "type": "integer", "minimum": 0 } }, "required": [ "name", "cloudUrl", "linkUrl", "connected", "modelCount" ] } }, "ok": { "type": "boolean" }, "configPushed": { "type": "boolean" } }, "required": [ "connected", "cloudUrl", "linkUrl", "activeProfileName", "profiles", "ok", "configPushed" ] } } } } } } }, "/api/internal/desktop/cloud-models": { "put": { "tags": [ "Desktop" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabledModelIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "enabledModelIds" ] } } } }, "responses": { "200": { "description": "Cloud models", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "ok" ] } } } } } } }, "/api/internal/desktop/default-model": { "get": { "tags": [ "Desktop" ], "responses": { "200": { "description": "Default model", "content": { "application/json": { "schema": { "type": "object", "properties": { "modelId": { "type": "string", "nullable": true } }, "required": [ "modelId" ] } } } } } }, "put": { "tags": [ "Desktop" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "modelId": { "type": "string" } }, "required": [ "modelId" ] } } } }, "responses": { "200": { "description": "Set default model", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "modelId": { "type": "string" }, "configPushed": { "type": "boolean" } }, "required": [ "ok", "modelId", "configPushed" ] } } } } } } }, "/api/internal/desktop/rewards": { "get": { "tags": [ "Desktop" ], "responses": { "200": { "description": "Desktop rewards status", "content": { "application/json": { "schema": { "type": "object", "properties": { "viewer": { "type": "object", "properties": { "cloudConnected": { "type": "boolean" }, "activeModelId": { "type": "string", "nullable": true }, "activeModelProviderId": { "type": "string", "nullable": true }, "usingManagedModel": { "type": "boolean" } }, "required": [ "cloudConnected", "activeModelId", "activeModelProviderId", "usingManagedModel" ] }, "progress": { "type": "object", "properties": { "claimedCount": { "type": "integer", "minimum": 0 }, "totalCount": { "type": "integer", "minimum": 0 }, "earnedCredits": { "type": "number", "minimum": 0 }, "availableCredits": { "type": "number", "minimum": 0 } }, "required": [ "claimedCount", "totalCount", "earnedCredits" ] }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "daily_checkin", "github_star", "x_share", "reddit", "mobile_share", "lingying", "facebook", "whatsapp" ] }, "group": { "type": "string", "enum": [ "daily", "opensource", "social" ] }, "icon": { "type": "string" }, "reward": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "shareMode": { "type": "string", "enum": [ "link", "tweet", "image" ] }, "repeatMode": { "type": "string", "enum": [ "once", "daily", "weekly" ] }, "requiresScreenshot": { "type": "boolean" }, "actionUrl": { "type": "string", "nullable": true, "format": "uri", "default": null }, "isClaimed": { "type": "boolean" }, "lastClaimedAt": { "type": "string", "nullable": true }, "claimCount": { "type": "integer", "minimum": 0 } }, "required": [ "id", "group", "icon", "reward", "shareMode", "repeatMode", "requiresScreenshot", "isClaimed", "lastClaimedAt", "claimCount" ] } }, "cloudBalance": { "type": "object", "nullable": true, "properties": { "totalBalance": { "type": "integer", "minimum": 0 }, "totalRecharged": { "type": "integer", "minimum": 0 }, "totalConsumed": { "type": "integer", "minimum": 0 }, "giftedBalance": { "type": "integer", "minimum": 0 }, "planBalance": { "type": "integer", "minimum": 0 } }, "default": null, "required": [ "totalBalance", "totalRecharged", "totalConsumed" ] }, "autoFallbackTriggered": { "type": "boolean" } }, "required": [ "viewer", "progress", "tasks" ] } } } } } } }, "/api/internal/desktop/rewards/github-star-session": { "post": { "tags": [ "Desktop" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Prepare a GitHub star verification session", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 }, "baselineStars": { "type": "integer", "minimum": 0 }, "expiresAt": { "type": "string" } }, "required": [ "sessionId", "baselineStars", "expiresAt" ] } } } }, "400": { "description": "GitHub star verification is temporarily unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/internal/desktop/rewards/claim": { "post": { "tags": [ "Desktop" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "enum": [ "daily_checkin", "github_star", "x_share", "reddit", "mobile_share", "lingying", "facebook", "whatsapp" ] }, "proof": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "githubSessionId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "additionalProperties": false } }, "required": [ "taskId" ] } } } }, "responses": { "200": { "description": "Claim a desktop reward", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "alreadyClaimed": { "type": "boolean" }, "status": { "type": "object", "properties": { "viewer": { "type": "object", "properties": { "cloudConnected": { "type": "boolean" }, "activeModelId": { "type": "string", "nullable": true }, "activeModelProviderId": { "type": "string", "nullable": true }, "usingManagedModel": { "type": "boolean" } }, "required": [ "cloudConnected", "activeModelId", "activeModelProviderId", "usingManagedModel" ] }, "progress": { "type": "object", "properties": { "claimedCount": { "type": "integer", "minimum": 0 }, "totalCount": { "type": "integer", "minimum": 0 }, "earnedCredits": { "type": "number", "minimum": 0 }, "availableCredits": { "type": "number", "minimum": 0 } }, "required": [ "claimedCount", "totalCount", "earnedCredits" ] }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "daily_checkin", "github_star", "x_share", "reddit", "mobile_share", "lingying", "facebook", "whatsapp" ] }, "group": { "type": "string", "enum": [ "daily", "opensource", "social" ] }, "icon": { "type": "string" }, "reward": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "shareMode": { "type": "string", "enum": [ "link", "tweet", "image" ] }, "repeatMode": { "type": "string", "enum": [ "once", "daily", "weekly" ] }, "requiresScreenshot": { "type": "boolean" }, "actionUrl": { "type": "string", "nullable": true, "format": "uri", "default": null }, "isClaimed": { "type": "boolean" }, "lastClaimedAt": { "type": "string", "nullable": true }, "claimCount": { "type": "integer", "minimum": 0 } }, "required": [ "id", "group", "icon", "reward", "shareMode", "repeatMode", "requiresScreenshot", "isClaimed", "lastClaimedAt", "claimCount" ] } }, "cloudBalance": { "type": "object", "nullable": true, "properties": { "totalBalance": { "type": "integer", "minimum": 0 }, "totalRecharged": { "type": "integer", "minimum": 0 }, "totalConsumed": { "type": "integer", "minimum": 0 }, "giftedBalance": { "type": "integer", "minimum": 0 }, "planBalance": { "type": "integer", "minimum": 0 } }, "default": null, "required": [ "totalBalance", "totalRecharged", "totalConsumed" ] }, "autoFallbackTriggered": { "type": "boolean" } }, "required": [ "viewer", "progress", "tasks" ] } }, "required": [ "ok", "alreadyClaimed", "status" ] } } } }, "400": { "description": "Invalid claim proof", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/internal/desktop/rewards/set-balance": { "post": { "tags": [ "Desktop" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "integer", "minimum": 0 } }, "required": [ "balance" ] } } } }, "responses": { "200": { "description": "Update the desktop test balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "viewer": { "type": "object", "properties": { "cloudConnected": { "type": "boolean" }, "activeModelId": { "type": "string", "nullable": true }, "activeModelProviderId": { "type": "string", "nullable": true }, "usingManagedModel": { "type": "boolean" } }, "required": [ "cloudConnected", "activeModelId", "activeModelProviderId", "usingManagedModel" ] }, "progress": { "type": "object", "properties": { "claimedCount": { "type": "integer", "minimum": 0 }, "totalCount": { "type": "integer", "minimum": 0 }, "earnedCredits": { "type": "number", "minimum": 0 }, "availableCredits": { "type": "number", "minimum": 0 } }, "required": [ "claimedCount", "totalCount", "earnedCredits" ] }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "daily_checkin", "github_star", "x_share", "reddit", "mobile_share", "lingying", "facebook", "whatsapp" ] }, "group": { "type": "string", "enum": [ "daily", "opensource", "social" ] }, "icon": { "type": "string" }, "reward": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "shareMode": { "type": "string", "enum": [ "link", "tweet", "image" ] }, "repeatMode": { "type": "string", "enum": [ "once", "daily", "weekly" ] }, "requiresScreenshot": { "type": "boolean" }, "actionUrl": { "type": "string", "nullable": true, "format": "uri", "default": null }, "isClaimed": { "type": "boolean" }, "lastClaimedAt": { "type": "string", "nullable": true }, "claimCount": { "type": "integer", "minimum": 0 } }, "required": [ "id", "group", "icon", "reward", "shareMode", "repeatMode", "requiresScreenshot", "isClaimed", "lastClaimedAt", "claimCount" ] } }, "cloudBalance": { "type": "object", "nullable": true, "properties": { "totalBalance": { "type": "integer", "minimum": 0 }, "totalRecharged": { "type": "integer", "minimum": 0 }, "totalConsumed": { "type": "integer", "minimum": 0 }, "giftedBalance": { "type": "integer", "minimum": 0 }, "planBalance": { "type": "integer", "minimum": 0 } }, "default": null, "required": [ "totalBalance", "totalRecharged", "totalConsumed" ] }, "autoFallbackTriggered": { "type": "boolean" } }, "required": [ "viewer", "progress", "tasks" ] } } } }, "400": { "description": "Unable to update the desktop test balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels": { "get": { "tags": [ "Channels" ], "responses": { "200": { "description": "Channel list", "content": { "application/json": { "schema": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "channelType": { "type": "string", "enum": [ "slack", "discord", "feishu", "dingtalk", "wecom", "wechat", "telegram", "whatsapp", "qqbot" ] }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "error" ] }, "teamName": { "type": "string", "nullable": true }, "appId": { "type": "string", "nullable": true }, "botUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "channelType", "accountId", "status", "teamName", "createdAt", "updatedAt" ] } } }, "required": [ "channels" ] } } } } } } }, "/api/v1/channels/slack/redirect-uri": { "get": { "tags": [ "Channels" ], "responses": { "200": { "description": "Deprecated Slack redirect URI", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUri": { "type": "string" } }, "required": [ "redirectUri" ] } } } } } } }, "/api/v1/channels/slack/oauth-url": { "get": { "tags": [ "Channels" ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "returnTo", "in": "query" } ], "responses": { "200": { "description": "Deprecated Slack OAuth placeholder", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "redirectUri": { "type": "string" } }, "required": [ "url", "redirectUri" ] } } } } } } }, "/api/v1/channels/slack/connect": { "post": { "tags": [ "Channels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "botToken": { "type": "string", "minLength": 1 }, "signingSecret": { "type": "string", "minLength": 1 }, "teamId": { "type": "string" }, "teamName": { "type": "string" }, "appId": { "type": "string" } }, "required": [ "botToken", "signingSecret" ] } } } }, "responses": { "200": { "description": "Connected slack channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "channelType": { "type": "string", "enum": [ "slack", "discord", "feishu", "dingtalk", "wecom", "wechat", "telegram", "whatsapp", "qqbot" ] }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "error" ] }, "teamName": { "type": "string", "nullable": true }, "appId": { "type": "string", "nullable": true }, "botUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "channelType", "accountId", "status", "teamName", "createdAt", "updatedAt" ] } } } }, "409": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/discord/connect": { "post": { "tags": [ "Channels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "botToken": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "guildId": { "type": "string" }, "guildName": { "type": "string" } }, "required": [ "botToken", "appId" ] } } } }, "responses": { "200": { "description": "Connected discord channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "channelType": { "type": "string", "enum": [ "slack", "discord", "feishu", "dingtalk", "wecom", "wechat", "telegram", "whatsapp", "qqbot" ] }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "error" ] }, "teamName": { "type": "string", "nullable": true }, "appId": { "type": "string", "nullable": true }, "botUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "channelType", "accountId", "status", "teamName", "createdAt", "updatedAt" ] } } } }, "409": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/feishu/connect": { "post": { "tags": [ "Channels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "appSecret": { "type": "string", "minLength": 1 }, "connectionMode": { "type": "string", "enum": [ "websocket", "webhook" ] }, "verificationToken": { "type": "string" } }, "required": [ "appId", "appSecret" ] } } } }, "responses": { "200": { "description": "Connected feishu channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "channelType": { "type": "string", "enum": [ "slack", "discord", "feishu", "dingtalk", "wecom", "wechat", "telegram", "whatsapp", "qqbot" ] }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "error" ] }, "teamName": { "type": "string", "nullable": true }, "appId": { "type": "string", "nullable": true }, "botUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "channelType", "accountId", "status", "teamName", "createdAt", "updatedAt" ] } } } }, "409": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/telegram/connect": { "post": { "tags": [ "Channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "botToken": { "type": "string", "minLength": 1 } }, "required": [ "botToken" ] } } } }, "responses": { "200": { "description": "Connected telegram channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "channelType": { "type": "string", "enum": [ "slack", "discord", "feishu", "dingtalk", "wecom", "wechat", "telegram", "whatsapp", "qqbot" ] }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "error" ] }, "teamName": { "type": "string", "nullable": true }, "appId": { "type": "string", "nullable": true }, "botUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "channelType", "accountId", "status", "teamName", "createdAt", "updatedAt" ] } } } }, "409": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/dingtalk/connect": { "post": { "tags": [ "Channels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1 }, "clientSecret": { "type": "string", "minLength": 1 } }, "required": [ "clientId", "clientSecret" ] } } } }, "responses": { "200": { "description": "Connected dingtalk channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "channelType": { "type": "string", "enum": [ "slack", "discord", "feishu", "dingtalk", "wecom", "wechat", "telegram", "whatsapp", "qqbot" ] }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "error" ] }, "teamName": { "type": "string", "nullable": true }, "appId": { "type": "string", "nullable": true }, "botUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "channelType", "accountId", "status", "teamName", "createdAt", "updatedAt" ] } } } }, "409": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/dingtalk/test": { "post": { "tags": [ "Channels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1 }, "clientSecret": { "type": "string", "minLength": 1 } }, "required": [ "clientId", "clientSecret" ] } } } }, "responses": { "200": { "description": "DingTalk connectivity test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "409": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/qqbot/connect": { "post": { "tags": [ "Channels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "appSecret": { "type": "string", "minLength": 1 } }, "required": [ "appId", "appSecret" ] } } } }, "responses": { "200": { "description": "Connected qqbot channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "channelType": { "type": "string", "enum": [ "slack", "discord", "feishu", "dingtalk", "wecom", "wechat", "telegram", "whatsapp", "qqbot" ] }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "error" ] }, "teamName": { "type": "string", "nullable": true }, "appId": { "type": "string", "nullable": true }, "botUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "channelType", "accountId", "status", "teamName", "createdAt", "updatedAt" ] } } } }, "409": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/qqbot/test": { "post": { "tags": [ "Channels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "appSecret": { "type": "string", "minLength": 1 } }, "required": [ "appId", "appSecret" ] } } } }, "responses": { "200": { "description": "QQ connectivity test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "409": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/wecom/connect": { "post": { "tags": [ "Channels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "botId": { "type": "string", "minLength": 1 }, "secret": { "type": "string", "minLength": 1 } }, "required": [ "botId", "secret" ] } } } }, "responses": { "200": { "description": "Connected wecom channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "channelType": { "type": "string", "enum": [ "slack", "discord", "feishu", "dingtalk", "wecom", "wechat", "telegram", "whatsapp", "qqbot" ] }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "error" ] }, "teamName": { "type": "string", "nullable": true }, "appId": { "type": "string", "nullable": true }, "botUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "channelType", "accountId", "status", "teamName", "createdAt", "updatedAt" ] } } } }, "409": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/wecom/test": { "post": { "tags": [ "Channels" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "botId": { "type": "string", "minLength": 1 }, "secret": { "type": "string", "minLength": 1 } }, "required": [ "botId", "secret" ] } } } }, "responses": { "200": { "description": "WeCom connectivity test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "409": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/{channelId}/status": { "get": { "tags": [ "Channels" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "channelId", "in": "path" } ], "responses": { "200": { "description": "Channel status", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "channelType": { "type": "string", "enum": [ "slack", "discord", "feishu", "dingtalk", "wecom", "wechat", "telegram", "whatsapp", "qqbot" ] }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "error" ] }, "teamName": { "type": "string", "nullable": true }, "appId": { "type": "string", "nullable": true }, "botUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "channelType", "accountId", "status", "teamName", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/bot-quota": { "get": { "tags": [ "Channels" ], "responses": { "200": { "description": "Bot quota", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "resetsAt": { "type": "string" }, "usingByok": { "type": "boolean" }, "byokAvailable": { "type": "boolean" }, "autoFallbackTriggered": { "type": "boolean" } }, "required": [ "available", "resetsAt" ] } } } } } } }, "/api/v1/channels/{channelId}": { "delete": { "tags": [ "Channels" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "channelId", "in": "path" } ], "responses": { "200": { "description": "Disconnected channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } } } }, "/api/v1/channels/whatsapp/qr-start": { "post": { "tags": [ "Channels" ], "responses": { "200": { "description": "QR code data for WhatsApp login", "content": { "application/json": { "schema": { "type": "object", "properties": { "qrDataUrl": { "type": "string" }, "message": { "type": "string" }, "accountId": { "type": "string" }, "alreadyLinked": { "type": "boolean", "default": false } }, "required": [ "message", "accountId" ] } } } }, "502": { "description": "WhatsApp login unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/whatsapp/qr-wait": { "post": { "tags": [ "Channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 } }, "required": [ "accountId" ] } } } }, "responses": { "200": { "description": "WhatsApp QR login result", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "message": { "type": "string" }, "accountId": { "type": "string" } }, "required": [ "connected", "message", "accountId" ] } } } }, "502": { "description": "WhatsApp login unavailable or timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/whatsapp/connect": { "post": { "tags": [ "Channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 } }, "required": [ "accountId" ] } } } }, "responses": { "200": { "description": "Connected whatsapp channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "channelType": { "type": "string", "enum": [ "slack", "discord", "feishu", "dingtalk", "wecom", "wechat", "telegram", "whatsapp", "qqbot" ] }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "error" ] }, "teamName": { "type": "string", "nullable": true }, "appId": { "type": "string", "nullable": true }, "botUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "channelType", "accountId", "status", "teamName", "createdAt", "updatedAt" ] } } } }, "409": { "description": "Connection failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/wechat/qr-start": { "post": { "tags": [ "Channels" ], "responses": { "200": { "description": "QR code data for WeChat login", "content": { "application/json": { "schema": { "type": "object", "properties": { "qrDataUrl": { "type": "string" }, "message": { "type": "string" }, "sessionKey": { "type": "string" } }, "required": [ "message" ] } } } }, "502": { "description": "Gateway not connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/wechat/qr-wait": { "post": { "tags": [ "Channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionKey": { "type": "string", "minLength": 1 } }, "required": [ "sessionKey" ] } } } }, "responses": { "200": { "description": "WeChat QR login result", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "message": { "type": "string" }, "accountId": { "type": "string" } }, "required": [ "connected", "message" ] } } } }, "502": { "description": "Gateway not connected or timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/wechat/connect": { "post": { "tags": [ "Channels" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "minLength": 1 } }, "required": [ "accountId" ] } } } }, "responses": { "200": { "description": "Connected wechat channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "channelType": { "type": "string", "enum": [ "slack", "discord", "feishu", "dingtalk", "wecom", "wechat", "telegram", "whatsapp", "qqbot" ] }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "error" ] }, "teamName": { "type": "string", "nullable": true }, "appId": { "type": "string", "nullable": true }, "botUserId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "channelType", "accountId", "status", "teamName", "createdAt", "updatedAt" ] } } } }, "409": { "description": "Connection failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/channels/live-status": { "get": { "tags": [ "Channels" ], "responses": { "200": { "description": "Live channel and agent status from OpenClaw gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "gatewayConnected": { "type": "boolean" }, "channels": { "type": "array", "items": { "type": "object", "properties": { "channelType": { "type": "string" }, "channelId": { "type": "string" }, "accountId": { "type": "string" }, "status": { "type": "string", "enum": [ "connected", "connecting", "disconnected", "error", "restarting" ] }, "ready": { "type": "boolean" }, "connected": { "type": "boolean" }, "running": { "type": "boolean" }, "configured": { "type": "boolean" }, "lastError": { "type": "string", "nullable": true } }, "required": [ "channelType", "channelId", "accountId", "status", "ready", "connected", "running", "configured", "lastError" ] } }, "agent": { "type": "object", "properties": { "modelId": { "type": "string", "nullable": true }, "modelName": { "type": "string", "nullable": true }, "alive": { "type": "boolean" } }, "required": [ "modelId", "modelName", "alive" ] } }, "required": [ "gatewayConnected", "channels", "agent" ] } } } } } } }, "/api/v1/channels/{channelId}/readiness": { "get": { "tags": [ "Channels" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "channelId", "in": "path" } ], "responses": { "200": { "description": "Channel readiness status from OpenClaw gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "connected": { "type": "boolean" }, "running": { "type": "boolean" }, "configured": { "type": "boolean" }, "lastError": { "type": "string", "nullable": true }, "gatewayConnected": { "type": "boolean" } }, "required": [ "ready", "connected", "running", "configured", "lastError", "gatewayConnected" ] } } } }, "404": { "description": "Channel not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/internal/sessions": { "post": { "tags": [ "Sessions", "Internal" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "botId": { "type": "string", "minLength": 1 }, "sessionKey": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "channelType": { "type": "string" }, "channelId": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "ended" ] }, "messageCount": { "type": "integer" }, "lastMessageAt": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "botId", "sessionKey", "title" ] } } } }, "responses": { "201": { "description": "Created or updated session", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "sessionKey": { "type": "string" }, "channelType": { "type": "string", "nullable": true }, "channelId": { "type": "string", "nullable": true }, "title": { "type": "string" }, "status": { "type": "string" }, "messageCount": { "type": "number" }, "lastMessageAt": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "sessionKey", "channelType", "channelId", "title", "status", "messageCount", "lastMessageAt", "metadata", "createdAt", "updatedAt" ] } } } } } } }, "/api/internal/sessions/{id}": { "patch": { "tags": [ "Sessions", "Internal" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "status": { "type": "string", "enum": [ "active", "ended" ] }, "messageCount": { "type": "integer" }, "lastMessageAt": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true } } } } } } }, "responses": { "200": { "description": "Updated session", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "sessionKey": { "type": "string" }, "channelType": { "type": "string", "nullable": true }, "channelId": { "type": "string", "nullable": true }, "title": { "type": "string" }, "status": { "type": "string" }, "messageCount": { "type": "number" }, "lastMessageAt": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "sessionKey", "channelType", "channelId", "title", "status", "messageCount", "lastMessageAt", "metadata", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/sessions": { "get": { "tags": [ "Sessions" ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "botId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "channelType", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Session list", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "sessionKey": { "type": "string" }, "channelType": { "type": "string", "nullable": true }, "channelId": { "type": "string", "nullable": true }, "title": { "type": "string" }, "status": { "type": "string" }, "messageCount": { "type": "number" }, "lastMessageAt": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "sessionKey", "channelType", "channelId", "title", "status", "messageCount", "lastMessageAt", "metadata", "createdAt", "updatedAt" ] } }, "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" } }, "required": [ "sessions", "total", "limit", "offset" ] } } } } } } }, "/api/v1/sessions/{id}": { "get": { "tags": [ "Sessions" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Session details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "sessionKey": { "type": "string" }, "channelType": { "type": "string", "nullable": true }, "channelId": { "type": "string", "nullable": true }, "title": { "type": "string" }, "status": { "type": "string" }, "messageCount": { "type": "number" }, "lastMessageAt": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "sessionKey", "channelType", "channelId", "title", "status", "messageCount", "lastMessageAt", "metadata", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } }, "delete": { "tags": [ "Sessions" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delete session", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } } } }, "/api/v1/sessions/{id}/reset": { "post": { "tags": [ "Sessions" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Reset session", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "sessionKey": { "type": "string" }, "channelType": { "type": "string", "nullable": true }, "channelId": { "type": "string", "nullable": true }, "title": { "type": "string" }, "status": { "type": "string" }, "messageCount": { "type": "number" }, "lastMessageAt": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "sessionKey", "channelType", "channelId", "title", "status", "messageCount", "lastMessageAt", "metadata", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/sessions/{id}/messages": { "get": { "tags": [ "Sessions" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Chat messages for the session", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "nullable": true }, "timestamp": { "type": "number", "nullable": true }, "createdAt": { "type": "string", "nullable": true } }, "required": [ "id", "role", "timestamp", "createdAt" ] } }, "sessionKey": { "type": "string", "nullable": true } }, "required": [ "messages", "sessionKey" ] } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/models": { "get": { "tags": [ "Models" ], "responses": { "200": { "description": "Model list", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string" }, "isDefault": { "type": "boolean" }, "description": { "type": "string" } }, "required": [ "id", "name", "provider" ] } } }, "required": [ "models" ] } } } } } } }, "/api/v1/model-providers/registry": { "get": { "tags": [ "Model Providers" ], "responses": { "200": { "description": "Model provider registry", "content": { "application/json": { "schema": { "type": "object", "properties": { "registry": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "canonicalOpenClawId": { "type": "string", "minLength": 1 }, "aliases": { "type": "array", "items": { "type": "string" } }, "authModes": { "type": "array", "items": { "type": "string", "enum": [ "api-key", "aws-sdk", "oauth", "token" ] } }, "apiKind": { "type": "string", "enum": [ "openai-completions", "openai-responses", "openai-codex-responses", "anthropic-messages", "google-generative-ai", "github-copilot", "bedrock-converse-stream", "ollama" ] }, "defaultBaseUrls": { "type": "array", "items": { "type": "string" } }, "controllerConfigurable": { "type": "boolean" }, "modelsPageVisible": { "type": "boolean" }, "region": { "type": "string", "enum": [ "global", "china", "local" ] }, "signupUrl": { "type": "string" }, "supportsCustomBaseUrl": { "type": "boolean" }, "supportsModelDiscovery": { "type": "boolean" }, "supportsProxyMode": { "type": "boolean" }, "managedByAuthProfiles": { "type": "boolean" }, "requiresOauthRegion": { "type": "boolean" }, "authHeader": { "type": "boolean" }, "defaultHeaders": { "type": "object", "additionalProperties": { "type": "string" } }, "experimental": { "type": "boolean" }, "hidden": { "type": "boolean" }, "displayName": { "type": "string", "minLength": 1 }, "displayNameKey": { "type": "string" }, "descriptionKey": { "type": "string" }, "apiDocsUrl": { "type": "string" }, "apiKeyPlaceholder": { "type": "string" }, "defaultProxyUrl": { "type": "string" }, "logo": { "type": "string" } }, "required": [ "id", "canonicalOpenClawId", "aliases", "authModes", "apiKind", "defaultBaseUrls", "displayName" ] } } }, "required": [ "registry" ] } } } } } } }, "/api/v1/model-providers/config": { "get": { "tags": [ "Model Providers" ], "responses": { "200": { "description": "Model provider config document", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" }, "providers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "providerTemplateId": { "type": "string", "minLength": 1 }, "instanceId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean", "default": true }, "auth": { "type": "string", "enum": [ "api-key", "aws-sdk", "oauth", "token" ] }, "api": { "type": "string", "enum": [ "openai-completions", "openai-responses", "openai-codex-responses", "anthropic-messages", "google-generative-ai", "github-copilot", "bedrock-converse-stream", "ollama" ] }, "apiKey": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "env", "file", "exec" ] }, "provider": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } }, "required": [ "source", "provider", "id" ] } ] }, "baseUrl": { "type": "string", "minLength": 1 }, "oauthRegion": { "type": "string", "nullable": true, "enum": [ "global", "cn" ] }, "oauthProfileRef": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "headers": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "env", "file", "exec" ] }, "provider": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } }, "required": [ "source", "provider", "id" ] } ] } }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "api": { "type": "string", "enum": [ "openai-completions", "openai-responses", "openai-codex-responses", "anthropic-messages", "google-generative-ai", "github-copilot", "bedrock-converse-stream", "ollama" ] }, "reasoning": { "type": "boolean", "default": false }, "input": { "type": "array", "items": { "type": "string", "enum": [ "text", "image" ] }, "default": [ "text" ] }, "cost": { "type": "object", "properties": { "input": { "type": "number" }, "output": { "type": "number" }, "cacheRead": { "type": "number" }, "cacheWrite": { "type": "number" } }, "default": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "required": [ "input", "output", "cacheRead", "cacheWrite" ] }, "contextWindow": { "type": "number", "default": 0 }, "maxTokens": { "type": "number", "default": 0 }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "compat": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "id", "name" ] }, "default": [] }, "metadata": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "baseUrl" ] }, "default": {} }, "bedrockDiscovery": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "region": { "type": "string" }, "providerFilter": { "type": "array", "items": { "type": "string" } }, "refreshInterval": { "type": "number" }, "defaultContextWindow": { "type": "number" }, "defaultMaxTokens": { "type": "number" } } } } } }, "required": [ "config" ] } } } } } }, "put": { "tags": [ "Model Providers" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" }, "providers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "providerTemplateId": { "type": "string", "minLength": 1 }, "instanceId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean", "default": true }, "auth": { "type": "string", "enum": [ "api-key", "aws-sdk", "oauth", "token" ] }, "api": { "type": "string", "enum": [ "openai-completions", "openai-responses", "openai-codex-responses", "anthropic-messages", "google-generative-ai", "github-copilot", "bedrock-converse-stream", "ollama" ] }, "apiKey": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "env", "file", "exec" ] }, "provider": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } }, "required": [ "source", "provider", "id" ] } ] }, "baseUrl": { "type": "string", "minLength": 1 }, "oauthRegion": { "type": "string", "nullable": true, "enum": [ "global", "cn" ] }, "oauthProfileRef": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "headers": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "env", "file", "exec" ] }, "provider": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } }, "required": [ "source", "provider", "id" ] } ] } }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "api": { "type": "string", "enum": [ "openai-completions", "openai-responses", "openai-codex-responses", "anthropic-messages", "google-generative-ai", "github-copilot", "bedrock-converse-stream", "ollama" ] }, "reasoning": { "type": "boolean", "default": false }, "input": { "type": "array", "items": { "type": "string", "enum": [ "text", "image" ] }, "default": [ "text" ] }, "cost": { "type": "object", "properties": { "input": { "type": "number" }, "output": { "type": "number" }, "cacheRead": { "type": "number" }, "cacheWrite": { "type": "number" } }, "default": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "required": [ "input", "output", "cacheRead", "cacheWrite" ] }, "contextWindow": { "type": "number", "default": 0 }, "maxTokens": { "type": "number", "default": 0 }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "compat": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "id", "name" ] }, "default": [] }, "metadata": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "baseUrl" ] }, "default": {} }, "bedrockDiscovery": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "region": { "type": "string" }, "providerFilter": { "type": "array", "items": { "type": "string" } }, "refreshInterval": { "type": "number" }, "defaultContextWindow": { "type": "number" }, "defaultMaxTokens": { "type": "number" } } } } } } } }, "responses": { "200": { "description": "Updated model provider config document", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "merge", "replace" ], "default": "merge" }, "providers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "providerTemplateId": { "type": "string", "minLength": 1 }, "instanceId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean", "default": true }, "auth": { "type": "string", "enum": [ "api-key", "aws-sdk", "oauth", "token" ] }, "api": { "type": "string", "enum": [ "openai-completions", "openai-responses", "openai-codex-responses", "anthropic-messages", "google-generative-ai", "github-copilot", "bedrock-converse-stream", "ollama" ] }, "apiKey": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "env", "file", "exec" ] }, "provider": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } }, "required": [ "source", "provider", "id" ] } ] }, "baseUrl": { "type": "string", "minLength": 1 }, "oauthRegion": { "type": "string", "nullable": true, "enum": [ "global", "cn" ] }, "oauthProfileRef": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "headers": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "env", "file", "exec" ] }, "provider": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 } }, "required": [ "source", "provider", "id" ] } ] } }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "api": { "type": "string", "enum": [ "openai-completions", "openai-responses", "openai-codex-responses", "anthropic-messages", "google-generative-ai", "github-copilot", "bedrock-converse-stream", "ollama" ] }, "reasoning": { "type": "boolean", "default": false }, "input": { "type": "array", "items": { "type": "string", "enum": [ "text", "image" ] }, "default": [ "text" ] }, "cost": { "type": "object", "properties": { "input": { "type": "number" }, "output": { "type": "number" }, "cacheRead": { "type": "number" }, "cacheWrite": { "type": "number" } }, "default": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "required": [ "input", "output", "cacheRead", "cacheWrite" ] }, "contextWindow": { "type": "number", "default": 0 }, "maxTokens": { "type": "number", "default": 0 }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "compat": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "id", "name" ] }, "default": [] }, "metadata": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "baseUrl" ] }, "default": {} }, "bedrockDiscovery": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "region": { "type": "string" }, "providerFilter": { "type": "array", "items": { "type": "string" } }, "refreshInterval": { "type": "number" }, "defaultContextWindow": { "type": "number" }, "defaultMaxTokens": { "type": "number" } } } } } }, "required": [ "config" ] } } } } } } }, "/api/v1/model-providers/instances/validate": { "post": { "tags": [ "Model Providers" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string" }, "baseUrl": { "type": "string" }, "instanceKey": { "type": "string", "minLength": 1 } }, "required": [ "instanceKey" ] } } } }, "responses": { "200": { "description": "Validate model provider instance credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "models": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } }, "required": [ "valid" ] } } } } } } }, "/api/v1/model-providers/{providerId}/validate": { "post": { "tags": [ "Model Providers" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "providerId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string" }, "baseUrl": { "type": "string" } } } } } }, "responses": { "200": { "description": "Validate model provider credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "models": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } }, "required": [ "valid" ] } } } } } } }, "/api/v1/model-providers/minimax/oauth/status": { "get": { "tags": [ "Model Providers" ], "responses": { "200": { "description": "MiniMax OAuth status", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "inProgress": { "type": "boolean" }, "region": { "type": "string", "nullable": true, "enum": [ "global", "cn" ] }, "error": { "type": "string", "nullable": true } }, "required": [ "connected", "inProgress" ] } } } } } } }, "/api/v1/model-providers/minimax/oauth/login": { "post": { "tags": [ "Model Providers" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "region": { "type": "string", "enum": [ "global", "cn" ] } }, "required": [ "region" ] } } } }, "responses": { "200": { "description": "Start MiniMax OAuth login", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "inProgress": { "type": "boolean" }, "region": { "type": "string", "nullable": true, "enum": [ "global", "cn" ] }, "error": { "type": "string", "nullable": true }, "started": { "type": "boolean" }, "browserUrl": { "type": "string" } }, "required": [ "connected", "inProgress", "started" ] } } } } } }, "delete": { "tags": [ "Model Providers" ], "responses": { "200": { "description": "Cancel MiniMax OAuth login", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "inProgress": { "type": "boolean" }, "region": { "type": "string", "nullable": true, "enum": [ "global", "cn" ] }, "error": { "type": "string", "nullable": true }, "cancelled": { "type": "boolean" } }, "required": [ "connected", "inProgress", "cancelled" ] } } } } } } }, "/api/v1/providers/{providerId}/verify": { "post": { "tags": [ "Providers" ], "parameters": [ { "schema": { "type": "string", "enum": [ "anthropic", "openai", "google", "ollama", "siliconflow", "ppio", "nvidia", "stepfun", "amazon-bedrock", "deepseek", "openrouter", "mistral", "xai", "together", "huggingface", "qwen", "volcengine", "qianfan", "vllm", "byteplus", "venice", "github-copilot", "xiaomi", "chutes", "minimax", "kimi", "glm", "moonshot", "zai" ] }, "required": true, "name": "providerId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string" }, "baseUrl": { "type": "string" } } } } } }, "responses": { "200": { "description": "Verify provider", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "models": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } }, "required": [ "valid" ] } } } } } } }, "/api/v1/quota/fallback-to-byok": { "post": { "tags": [ "Quota" ], "responses": { "200": { "description": "Trigger automatic fallback to BYOK provider", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "newModelId": { "type": "string" } }, "required": [ "ok" ] } } } } } } }, "/api/v1/quota/restore-managed": { "post": { "tags": [ "Quota" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "managedModelId": { "type": "string", "minLength": 1 } }, "required": [ "managedModelId" ] } } } }, "responses": { "200": { "description": "Restore default model to managed (cloud) model", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "newModelId": { "type": "string" } }, "required": [ "ok" ] } } } } } } }, "/api/v1/model-providers/{providerId}/oauth/start": { "post": { "tags": [ "Model Providers" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "providerId", "in": "path" } ], "responses": { "200": { "description": "OAuth flow started", "content": { "application/json": { "schema": { "type": "object", "properties": { "browserUrl": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "/api/v1/model-providers/{providerId}/oauth/status": { "get": { "tags": [ "Model Providers" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "providerId", "in": "path" } ], "responses": { "200": { "description": "Current OAuth flow status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "idle", "pending", "completed", "failed" ] }, "error": { "type": "string" }, "models": { "type": "array", "items": { "type": "string" } } }, "required": [ "status" ] } } } } } } }, "/api/v1/model-providers/{providerId}/oauth/provider-status": { "get": { "tags": [ "Model Providers" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "providerId", "in": "path" } ], "responses": { "200": { "description": "OAuth provider connection status", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected": { "type": "boolean" }, "provider": { "type": "string" }, "expiresAt": { "type": "number" }, "remainingMs": { "type": "number" } }, "required": [ "connected" ] } } } } } } }, "/api/v1/model-providers/{providerId}/oauth/disconnect": { "post": { "tags": [ "Model Providers" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "providerId", "in": "path" } ], "responses": { "200": { "description": "OAuth provider disconnected", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } } } }, "/api/v1/integrations": { "get": { "tags": [ "Integrations" ], "responses": { "200": { "description": "Integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "toolkit": { "type": "object", "properties": { "slug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string" }, "fallbackIconUrl": { "type": "string" }, "category": { "type": "string" }, "authScheme": { "type": "string", "enum": [ "oauth2", "api_key_global", "api_key_user" ] }, "authFields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "secret" ] }, "placeholder": { "type": "string" } }, "required": [ "key", "label", "type" ] } } }, "required": [ "slug", "displayName", "description", "iconUrl", "fallbackIconUrl", "category", "authScheme" ] }, "status": { "type": "string", "enum": [ "pending", "initiated", "active", "failed", "expired", "disconnected" ] }, "connectUrl": { "type": "string" }, "connectedAt": { "type": "string" }, "credentialHints": { "type": "object", "additionalProperties": { "type": "string" } }, "returnTo": { "type": "string" }, "source": { "type": "string", "enum": [ "page", "chat" ] } }, "required": [ "toolkit", "status" ] } } }, "required": [ "integrations" ] } } } } } } }, "/api/v1/integrations/connect": { "post": { "tags": [ "Integrations" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "toolkitSlug": { "type": "string" }, "credentials": { "type": "object", "additionalProperties": { "type": "string" } }, "source": { "type": "string", "enum": [ "page", "chat" ] }, "returnTo": { "type": "string" } }, "required": [ "toolkitSlug" ] } } } }, "responses": { "200": { "description": "Connection initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "integration": { "type": "object", "properties": { "id": { "type": "string" }, "toolkit": { "type": "object", "properties": { "slug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string" }, "fallbackIconUrl": { "type": "string" }, "category": { "type": "string" }, "authScheme": { "type": "string", "enum": [ "oauth2", "api_key_global", "api_key_user" ] }, "authFields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "secret" ] }, "placeholder": { "type": "string" } }, "required": [ "key", "label", "type" ] } } }, "required": [ "slug", "displayName", "description", "iconUrl", "fallbackIconUrl", "category", "authScheme" ] }, "status": { "type": "string", "enum": [ "pending", "initiated", "active", "failed", "expired", "disconnected" ] }, "connectUrl": { "type": "string" }, "connectedAt": { "type": "string" }, "credentialHints": { "type": "object", "additionalProperties": { "type": "string" } }, "returnTo": { "type": "string" }, "source": { "type": "string", "enum": [ "page", "chat" ] } }, "required": [ "toolkit", "status" ] }, "connectUrl": { "type": "string" }, "state": { "type": "string" } }, "required": [ "integration" ] } } } } } } }, "/api/v1/integrations/{integrationId}/refresh": { "post": { "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "integrationId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string" } } } } } }, "responses": { "200": { "description": "Refreshed integration", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "toolkit": { "type": "object", "properties": { "slug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string" }, "fallbackIconUrl": { "type": "string" }, "category": { "type": "string" }, "authScheme": { "type": "string", "enum": [ "oauth2", "api_key_global", "api_key_user" ] }, "authFields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "secret" ] }, "placeholder": { "type": "string" } }, "required": [ "key", "label", "type" ] } } }, "required": [ "slug", "displayName", "description", "iconUrl", "fallbackIconUrl", "category", "authScheme" ] }, "status": { "type": "string", "enum": [ "pending", "initiated", "active", "failed", "expired", "disconnected" ] }, "connectUrl": { "type": "string" }, "connectedAt": { "type": "string" }, "credentialHints": { "type": "object", "additionalProperties": { "type": "string" } }, "returnTo": { "type": "string" }, "source": { "type": "string", "enum": [ "page", "chat" ] } }, "required": [ "toolkit", "status" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/integrations/{integrationId}": { "delete": { "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "integrationId", "in": "path" } ], "responses": { "200": { "description": "Disconnected integration", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "toolkit": { "type": "object", "properties": { "slug": { "type": "string" }, "displayName": { "type": "string" }, "description": { "type": "string" }, "iconUrl": { "type": "string" }, "fallbackIconUrl": { "type": "string" }, "category": { "type": "string" }, "authScheme": { "type": "string", "enum": [ "oauth2", "api_key_global", "api_key_user" ] }, "authFields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "secret" ] }, "placeholder": { "type": "string" } }, "required": [ "key", "label", "type" ] } } }, "required": [ "slug", "displayName", "description", "iconUrl", "fallbackIconUrl", "category", "authScheme" ] }, "status": { "type": "string", "enum": [ "pending", "initiated", "active", "failed", "expired", "disconnected" ] }, "connectUrl": { "type": "string" }, "connectedAt": { "type": "string" }, "credentialHints": { "type": "object", "additionalProperties": { "type": "string" } }, "returnTo": { "type": "string" }, "source": { "type": "string", "enum": [ "page", "chat" ] } }, "required": [ "toolkit", "status" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/internal/artifacts": { "post": { "tags": [ "Artifacts", "Internal" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "botId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "sessionKey": { "type": "string" }, "chatId": { "type": "string" }, "threadId": { "type": "string" }, "channelType": { "type": "string" }, "channelId": { "type": "string" }, "artifactType": { "type": "string", "enum": [ "code", "content", "deployment" ] }, "source": { "type": "string", "enum": [ "coding", "content" ] }, "contentType": { "type": "string" }, "status": { "type": "string", "enum": [ "building", "live", "failed", "stopped" ] }, "previewUrl": { "type": "string", "format": "uri" }, "deployTarget": { "type": "string" }, "linesOfCode": { "type": "integer" }, "fileCount": { "type": "integer" }, "durationMs": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true } } }, "required": [ "botId", "title" ] } } } }, "responses": { "201": { "description": "Created artifact", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "sessionKey": { "type": "string", "nullable": true }, "channelType": { "type": "string", "nullable": true }, "channelId": { "type": "string", "nullable": true }, "title": { "type": "string" }, "artifactType": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "status": { "type": "string" }, "previewUrl": { "type": "string", "nullable": true }, "deployTarget": { "type": "string", "nullable": true }, "linesOfCode": { "type": "number", "nullable": true }, "fileCount": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "sessionKey", "channelType", "channelId", "title", "artifactType", "source", "contentType", "status", "previewUrl", "deployTarget", "linesOfCode", "fileCount", "durationMs", "metadata", "createdAt", "updatedAt" ] } } } } } } }, "/api/internal/artifacts/{id}": { "patch": { "tags": [ "Artifacts", "Internal" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "status": { "type": "string", "enum": [ "building", "live", "failed", "stopped" ] }, "previewUrl": { "type": "string", "format": "uri" }, "deployTarget": { "type": "string" }, "linesOfCode": { "type": "integer" }, "fileCount": { "type": "integer" }, "durationMs": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true } } } } } } }, "responses": { "200": { "description": "Updated artifact", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "sessionKey": { "type": "string", "nullable": true }, "channelType": { "type": "string", "nullable": true }, "channelId": { "type": "string", "nullable": true }, "title": { "type": "string" }, "artifactType": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "status": { "type": "string" }, "previewUrl": { "type": "string", "nullable": true }, "deployTarget": { "type": "string", "nullable": true }, "linesOfCode": { "type": "number", "nullable": true }, "fileCount": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "sessionKey", "channelType", "channelId", "title", "artifactType", "source", "contentType", "status", "previewUrl", "deployTarget", "linesOfCode", "fileCount", "durationMs", "metadata", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Artifact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/artifacts": { "get": { "tags": [ "Artifacts" ], "parameters": [ { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "sessionKey", "in": "query" } ], "responses": { "200": { "description": "Artifacts", "content": { "application/json": { "schema": { "type": "object", "properties": { "artifacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "sessionKey": { "type": "string", "nullable": true }, "channelType": { "type": "string", "nullable": true }, "channelId": { "type": "string", "nullable": true }, "title": { "type": "string" }, "artifactType": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "status": { "type": "string" }, "previewUrl": { "type": "string", "nullable": true }, "deployTarget": { "type": "string", "nullable": true }, "linesOfCode": { "type": "number", "nullable": true }, "fileCount": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "sessionKey", "channelType", "channelId", "title", "artifactType", "source", "contentType", "status", "previewUrl", "deployTarget", "linesOfCode", "fileCount", "durationMs", "metadata", "createdAt", "updatedAt" ] } }, "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" } }, "required": [ "artifacts", "total", "limit", "offset" ] } } } } } } }, "/api/v1/artifacts/stats": { "get": { "tags": [ "Artifacts" ], "responses": { "200": { "description": "Artifact stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalArtifacts": { "type": "number" }, "liveCount": { "type": "number" }, "buildingCount": { "type": "number" }, "failedCount": { "type": "number" }, "codingCount": { "type": "number" }, "contentCount": { "type": "number" }, "totalLinesOfCode": { "type": "number" } }, "required": [ "totalArtifacts", "liveCount", "buildingCount", "failedCount", "codingCount", "contentCount", "totalLinesOfCode" ] } } } } } } }, "/api/v1/artifacts/{id}": { "get": { "tags": [ "Artifacts" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Artifact", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "botId": { "type": "string" }, "sessionKey": { "type": "string", "nullable": true }, "channelType": { "type": "string", "nullable": true }, "channelId": { "type": "string", "nullable": true }, "title": { "type": "string" }, "artifactType": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "status": { "type": "string" }, "previewUrl": { "type": "string", "nullable": true }, "deployTarget": { "type": "string", "nullable": true }, "linesOfCode": { "type": "number", "nullable": true }, "fileCount": { "type": "number", "nullable": true }, "durationMs": { "type": "number", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "botId", "sessionKey", "channelType", "channelId", "title", "artifactType", "source", "contentType", "status", "previewUrl", "deployTarget", "linesOfCode", "fileCount", "durationMs", "metadata", "createdAt", "updatedAt" ] } } } }, "404": { "description": "Artifact not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } }, "delete": { "tags": [ "Artifacts" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted artifact", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } } } }, "/api/v1/skillhub/catalog": { "get": { "tags": [ "SkillHub" ], "responses": { "200": { "description": "SkillHub catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "downloads": { "type": "number" }, "stars": { "type": "number" }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "slug", "name", "description", "downloads", "stars", "tags", "version", "updatedAt" ] } }, "installedSlugs": { "type": "array", "items": { "type": "string" } }, "installedSkills": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "source": { "type": "string", "enum": [ "managed", "custom", "workspace", "user" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "installedAt": { "type": "string", "nullable": true }, "agentId": { "type": "string", "nullable": true }, "agentName": { "type": "string", "nullable": true } }, "required": [ "slug", "source", "name", "description", "installedAt", "agentId", "agentName" ] } }, "meta": { "type": "object", "nullable": true, "properties": { "version": { "type": "string" }, "updatedAt": { "type": "string" }, "skillCount": { "type": "number" } }, "required": [ "version", "updatedAt", "skillCount" ] }, "queue": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "source": { "type": "string", "enum": [ "managed", "custom", "workspace", "user" ] }, "status": { "type": "string", "enum": [ "queued", "downloading", "installing-deps", "done", "failed" ] }, "position": { "type": "number" }, "error": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true, "enum": [ "skill_not_found", "rate_limit", "unknown" ] }, "retries": { "type": "number" }, "enqueuedAt": { "type": "string" } }, "required": [ "slug", "source", "status", "position", "error", "errorCode", "retries", "enqueuedAt" ] } } }, "required": [ "skills", "installedSlugs", "installedSkills", "meta", "queue" ] } } } } } } }, "/api/v1/skillhub/install": { "post": { "tags": [ "SkillHub" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" }, "source": { "type": "string", "enum": [ "managed", "custom", "workspace", "user" ] }, "agentId": { "type": "string", "nullable": true } }, "required": [ "slug" ] } } } }, "responses": { "200": { "description": "Install", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "queued": { "type": "boolean" }, "slug": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "downloading", "installing-deps", "done", "failed" ] }, "position": { "type": "number" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } } } } }, "/api/v1/skillhub/uninstall": { "post": { "tags": [ "SkillHub" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" }, "source": { "type": "string", "enum": [ "managed", "custom", "workspace", "user" ] }, "agentId": { "type": "string", "nullable": true } }, "required": [ "slug" ] } } } }, "responses": { "200": { "description": "Uninstall", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } } } } }, "/api/v1/skillhub/refresh": { "post": { "tags": [ "SkillHub" ], "responses": { "200": { "description": "Refresh", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "skillCount": { "type": "number" }, "error": { "type": "string" } }, "required": [ "ok", "skillCount" ] } } } } } } }, "/api/v1/skillhub/skills/{slug}": { "get": { "tags": [ "SkillHub" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "enum": [ "managed", "custom", "workspace", "user" ] }, "required": false, "name": "source", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agentId", "in": "query" } ], "responses": { "200": { "description": "Skill detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "downloads": { "type": "number" }, "stars": { "type": "number" }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "string" }, "updatedAt": { "type": "string" }, "installed": { "type": "boolean" }, "installedSource": { "type": "string", "nullable": true, "enum": [ "managed", "custom", "workspace", "user" ] }, "agentId": { "type": "string", "nullable": true }, "uninstallable": { "type": "boolean" }, "skillContent": { "type": "string", "nullable": true }, "files": { "type": "array", "items": { "type": "string" } } }, "required": [ "slug", "name", "description", "downloads", "stars", "tags", "version", "updatedAt", "installed", "installedSource", "agentId", "uninstallable", "skillContent", "files" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/api/v1/skillhub/import": { "post": { "tags": [ "SkillHub" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": {} }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Import result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "slug": { "type": "string" }, "error": { "type": "string" } }, "required": [ "ok" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" } }, "required": [ "ok", "error" ] } } } } } } }, "/api/v1/me": { "get": { "tags": [ "User" ], "responses": { "200": { "description": "Current local user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string", "nullable": true }, "plan": { "type": "string" }, "inviteAccepted": { "type": "boolean" }, "onboardingCompleted": { "type": "boolean" }, "authSource": { "type": "string", "nullable": true } }, "required": [ "id", "email", "name", "plan", "inviteAccepted", "onboardingCompleted" ] } } } } } }, "patch": { "tags": [ "User" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "image": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "string", "pattern": "^data:image\\/(?:png|jpeg|jpg|webp|gif);base64,[A-Za-z0-9+/=]+$" }, { "nullable": true } ] } } } } } }, "responses": { "200": { "description": "Updated local user", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "profile": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string", "nullable": true }, "plan": { "type": "string" }, "inviteAccepted": { "type": "boolean" }, "onboardingCompleted": { "type": "boolean" }, "authSource": { "type": "string", "nullable": true } }, "required": [ "id", "email", "name", "plan", "inviteAccepted", "onboardingCompleted" ] } }, "required": [ "ok", "profile" ] } } } } } } }, "/api/v1/me/auth-source": { "post": { "tags": [ "User" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "email", "google", "slack_shared_claim", "IM", "Landing" ] }, "detail": { "type": "string" } }, "required": [ "source" ] } } } }, "responses": { "200": { "description": "Updated auth source", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } } } }, "/api/v1/runtime-config": { "get": { "tags": [ "Runtime Config" ], "responses": { "200": { "description": "Runtime config", "content": { "application/json": { "schema": { "type": "object", "properties": { "runtime": { "type": "object", "properties": { "gateway": { "type": "object", "properties": { "port": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "default": 18789 }, "bind": { "type": "string", "enum": [ "loopback", "lan", "auto" ], "default": "loopback" }, "authMode": { "type": "string", "enum": [ "none", "token" ], "default": "none" } }, "default": { "port": 18789, "bind": "loopback", "authMode": "none" } }, "defaultModelId": { "type": "string", "default": "link/gemini-3-flash-preview" } } } }, "required": [ "runtime" ] } } } } } }, "put": { "tags": [ "Runtime Config" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "gateway": { "type": "object", "properties": { "port": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "default": 18789 }, "bind": { "type": "string", "enum": [ "loopback", "lan", "auto" ], "default": "loopback" }, "authMode": { "type": "string", "enum": [ "none", "token" ], "default": "none" } }, "default": { "port": 18789, "bind": "loopback", "authMode": "none" } }, "defaultModelId": { "type": "string", "default": "link/gemini-3-flash-preview" } } } } } }, "responses": { "200": { "description": "Updated runtime config", "content": { "application/json": { "schema": { "type": "object", "properties": { "runtime": { "type": "object", "properties": { "gateway": { "type": "object", "properties": { "port": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "default": 18789 }, "bind": { "type": "string", "enum": [ "loopback", "lan", "auto" ], "default": "loopback" }, "authMode": { "type": "string", "enum": [ "none", "token" ], "default": "none" } }, "default": { "port": 18789, "bind": "loopback", "authMode": "none" } }, "defaultModelId": { "type": "string", "default": "link/gemini-3-flash-preview" } } } }, "required": [ "runtime" ] } } } } } } }, "/api/v1/workspace-templates": { "get": { "tags": [ "Workspace Templates" ], "responses": { "200": { "description": "Workspace templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "content": { "type": "string" }, "writeMode": { "type": "string", "enum": [ "seed", "inject" ], "default": "seed" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "content", "createdAt", "updatedAt" ] } } }, "required": [ "templates" ] } } } } } } }, "/api/internal/workspace-templates/latest": { "get": { "tags": [ "Internal" ], "responses": { "200": { "description": "Latest template runtime snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0 }, "templatesHash": { "type": "string" }, "templates": { "type": "object", "additionalProperties": { "type": "object", "properties": { "content": { "type": "string" }, "writeMode": { "type": "string", "enum": [ "seed", "inject" ] } }, "required": [ "content", "writeMode" ] } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "version", "templatesHash", "templates", "createdAt" ] } } } } } } }, "/api/internal/workspace-templates/{name}": { "put": { "tags": [ "Internal" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "name", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1 }, "writeMode": { "type": "string", "enum": [ "seed", "inject" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "Upserted template", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "name": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "ok", "name", "version" ] } } } } } } } } }