Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🔌 feat: OpenAPI spec and docs for the public Agents API (#15928)

Atef Bellaaj69f0dd2a121b
diff --git a/.github/workflows/backend-review.yml b/.github/workflows/backend-review.yml
index 8416585485..75c8c01ff1 100644
--- a/.github/workflows/backend-review.yml
+++ b/.github/workflows/backend-review.yml
@@ -308,6 +308,9 @@ jobs:
- name: Type check @librechat/api
run: npx tsc --noEmit -p packages/api/tsconfig.json
+ - name: OpenAPI spec drift check
+ run: npm run -w @librechat/api openapi:check
+
- name: Type check @librechat/client
run: npx tsc --noEmit -p packages/client/tsconfig.json
diff --git a/.prettierignore b/.prettierignore
new file mode 100644
index 0000000000..fff14af7ac
--- /dev/null
+++ b/.prettierignore
@@ -0,0 +1,3 @@
+# Generated artifact. Owned by `npm run -w @librechat/api openapi:generate`,
+# checked by `openapi:check`. Do not let Prettier reformat it.
+packages/api/openapi/agents.openapi.json
diff --git a/api/package.json b/api/package.json
index 1149d87d39..356b28bd08 100644
--- a/api/package.json
+++ b/api/package.json
@@ -129,6 +129,7 @@
"re2js": "^2.8.6",
"sanitize-html": "^2.17.7",
"sharp": "^0.35.4",
+ "swagger-ui-dist": "^5.32.15",
"ua-parser-js": "^1.0.36",
"undici": "^7.29.0",
"winston": "^3.11.0",
diff --git a/api/server/experimental.js b/api/server/experimental.js
index 61f1842ff3..ef3de373ce 100644
--- a/api/server/experimental.js
+++ b/api/server/experimental.js
@@ -669,6 +669,8 @@ if (cluster.isMaster) {
app.use('/api/tags', routes.tags);
app.use('/api/mcp', routes.mcp);
+ app.use('/api', routes.openapi);
+
/** 404 for unmatched API routes */
app.use('/api', apiNotFound);
diff --git a/api/server/index.js b/api/server/index.js
index b8c0ec5b51..610d5c2c9a 100644
--- a/api/server/index.js
+++ b/api/server/index.js
@@ -448,6 +448,8 @@ const startServer = async () => {
app.use('/metrics', metricsRouter);
+ app.use('/api', routes.openapi);
+
/** 404 for unmatched API routes */
app.use('/api', apiNotFound);
diff --git a/api/server/routes/index.js b/api/server/routes/index.js
index 7827559f11..14afa6f269 100644
--- a/api/server/routes/index.js
+++ b/api/server/routes/index.js
@@ -25,6 +25,7 @@ const balance = require('./balance');
const actions = require('./actions');
const apiKeys = require('./apiKeys');
const banner = require('./banner');
+const openapi = require('./openapi');
const search = require('./search');
const models = require('./models');
const convos = require('./convos');
@@ -68,6 +69,7 @@ module.exports = {
files,
share,
banner,
+ openapi,
agents,
convos,
traces,
diff --git a/api/server/routes/openapi.js b/api/server/routes/openapi.js
new file mode 100644
index 0000000000..fa5f82e0aa
--- /dev/null
+++ b/api/server/routes/openapi.js
@@ -0,0 +1,8 @@
+const swaggerUiDist = require('swagger-ui-dist');
+const { createOpenApiRouter } = require('@librechat/api');
+const { getAppConfig } = require('~/server/services/Config/app');
+
+module.exports = createOpenApiRouter({
+ getAppConfig,
+ swaggerAssetsPath: swaggerUiDist.getAbsoluteFSPath(),
+});
diff --git a/e2e/lighthouse/librechat.yaml b/e2e/lighthouse/librechat.yaml
index 494891c355..92ea7d6a4b 100644
--- a/e2e/lighthouse/librechat.yaml
+++ b/e2e/lighthouse/librechat.yaml
@@ -3,3 +3,5 @@ cache: true
endpoints:
openAI:
titleConvo: false
+openapi:
+ enabled: true
diff --git a/package-lock.json b/package-lock.json
index 35f5ed7c84..b3d3619865 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -147,6 +147,7 @@
"re2js": "^2.8.6",
"sanitize-html": "^2.17.7",
"sharp": "^0.35.4",
+ "swagger-ui-dist": "^5.32.15",
"ua-parser-js": "^1.0.36",
"undici": "^7.29.0",
"winston": "^3.11.0",
@@ -16556,6 +16557,13 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/@scarf/scarf": {
+ "version": "1.4.0",
+ "resolved": "https://registry.npmjs.org/@scarf/scarf/-/scarf-1.4.0.tgz",
+ "integrity": "sha512-xxeapPiUXdZAE3che6f3xogoJPeZgig6omHEy1rIY5WVsB3H2BHNnZH+gHG6x91SCWyQCzWGsuL2Hh3ClO5/qQ==",
+ "hasInstallScript": true,
+ "license": "Apache-2.0"
+ },
"node_modules/@sentry/conventions": {
"version": "0.16.0",
"resolved": "https://registry.npmjs.org/@sentry/conventions/-/conventions-0.16.0.tgz",
@@ -39324,6 +39332,15 @@
"url": "https://github.com/sponsors/ljharb"
}
},
+ "node_modules/swagger-ui-dist": {
+ "version": "5.32.15",
+ "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-5.32.15.tgz",
+ "integrity": "sha512-TSFER+rFQlf1nzk6WvKkMaHTxAPQ3eAAxigFThnxQedSREanfZgSbJFayZVs/ULnSbNdrJOb99vLD6xpb3R3eg==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "@scarf/scarf": "=1.4.0"
+ }
+ },
"node_modules/swr": {
"version": "2.3.8",
"resolved": "https://registry.npmjs.org/swr/-/swr-2.3.8.tgz",
@@ -42325,6 +42342,19 @@
"url": "https://github.com/sponsors/colinhacks"
}
},
+ "node_modules/zod-openapi": {
+ "version": "4.2.4",
+ "resolved": "https://registry.npmjs.org/zod-openapi/-/zod-openapi-4.2.4.tgz",
+ "integrity": "sha512-tsrQpbpqFCXqVXUzi3TPwFhuMtLN3oNZobOtYnK6/5VkXsNdnIgyNr4r8no4wmYluaxzN3F7iS+8xCW8BmMQ8g==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=18"
+ },
+ "peerDependencies": {
+ "zod": "^3.21.4"
+ }
+ },
"node_modules/zod-to-json-schema": {
"version": "3.25.1",
"resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.1.tgz",
@@ -42401,7 +42431,8 @@
"typescript": "^5.9.3",
"winston": "^3.17.0",
"xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
- "yauzl": "^3.2.1"
+ "yauzl": "^3.2.1",
+ "zod-openapi": "^4.2.4"
},
"peerDependencies": {
"@anthropic-ai/vertex-sdk": "^0.16.0",
diff --git a/packages/api/openapi/agents.openapi.json b/packages/api/openapi/agents.openapi.json
new file mode 100644
index 0000000000..3b1b3efe0d
--- /dev/null
+++ b/packages/api/openapi/agents.openapi.json
@@ -0,0 +1,3802 @@
+{
+ "openapi": "3.1.0",
+ "info": {
+ "title": "LibreChat Agents API",
+ "version": "0.1.0",
+ "description": "The public agent and skill management endpoints of the LibreChat Agents API. This API is in beta and may change."
+ },
+ "servers": [
+ {
+ "url": "agents/v1",
+ "description": "Relative to where this document is served (`/api/openapi.json`), so it resolves under any deployment base path."
+ }
+ ],
+ "paths": {
+ "/agents": {
+ "post": {
+ "operationId": "createAgent",
+ "summary": "Create an agent",
+ "tags": [
+ "Agents"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AgentCreateRequest"
+ }
+ }
+ }
+ },
+ "responses": {
+ "201": {
+ "description": "The created agent",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Agent"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "get": {
+ "operationId": "listAgents",
+ "summary": "List agents",
+ "tags": [
+ "Agents"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "query",
+ "name": "limit",
+ "schema": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 100,
+ "default": 20
+ }
+ },
+ {
+ "in": "query",
+ "name": "cursor",
+ "schema": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 512
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A page of agents",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AgentList"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/agents/{id}": {
+ "get": {
+ "operationId": "getAgent",
+ "summary": "Get an agent",
+ "tags": [
+ "Agents"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "path",
+ "name": "id",
+ "description": "The agent id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The agent",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Agent"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "patch": {
+ "operationId": "updateAgent",
+ "summary": "Update an agent",
+ "tags": [
+ "Agents"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "path",
+ "name": "id",
+ "description": "The agent id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ }
+ ],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AgentUpdateRequest"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "The updated agent",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Agent"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "delete": {
+ "operationId": "deleteAgent",
+ "summary": "Delete an agent",
+ "tags": [
+ "Agents"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "path",
+ "name": "id",
+ "description": "The agent id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The agent was deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AgentDeleted"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/agents/{id}/files": {
+ "post": {
+ "operationId": "uploadAgentFile",
+ "summary": "Upload a file to an agent",
+ "tags": [
+ "Agents"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "path",
+ "name": "id",
+ "description": "The agent id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ }
+ ],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "multipart/form-data": {
+ "schema": {
+ "type": "object",
+ "required": [
+ "file",
+ "purpose"
+ ],
+ "properties": {
+ "file": {
+ "type": "string",
+ "format": "binary"
+ },
+ "purpose": {
+ "type": "string",
+ "enum": [
+ "file_search",
+ "execute_code",
+ "context"
+ ],
+ "description": "The tool resource the file is uploaded for."
+ }
+ }
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "The uploaded file",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AgentFile"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "429": {
+ "description": "Too many upload requests",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "get": {
+ "operationId": "listAgentFiles",
+ "summary": "List an agent's files",
+ "tags": [
+ "Agents"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "path",
+ "name": "id",
+ "description": "The agent id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The agent's files",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AgentFileList"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/agents/{id}/files/{fileId}": {
+ "delete": {
+ "operationId": "deleteAgentFile",
+ "summary": "Delete an agent's file",
+ "tags": [
+ "Agents"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "path",
+ "name": "id",
+ "description": "The agent id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ },
+ {
+ "in": "path",
+ "name": "fileId",
+ "description": "The file id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The file was deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AgentFileDeleted"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/skills": {
+ "get": {
+ "operationId": "listSkills",
+ "summary": "List skills",
+ "tags": [
+ "Skills"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "query",
+ "name": "limit",
+ "schema": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": 100,
+ "default": 20
+ }
+ },
+ {
+ "in": "query",
+ "name": "cursor",
+ "schema": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 512
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A page of skills",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillList"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/skills/{id}": {
+ "get": {
+ "operationId": "getSkill",
+ "summary": "Get a skill",
+ "tags": [
+ "Skills"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "path",
+ "name": "id",
+ "description": "The skill id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The skill",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Skill"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "patch": {
+ "operationId": "updateSkill",
+ "summary": "Update a skill",
+ "tags": [
+ "Skills"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "path",
+ "name": "id",
+ "description": "The skill id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ }
+ ],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillUpdateRequest"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "The updated skill",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Skill"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The skill changed since the provided expectedVersion, or the bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/skills/{id}/files": {
+ "get": {
+ "operationId": "listSkillFiles",
+ "summary": "List a skill's files",
+ "tags": [
+ "Skills"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "path",
+ "name": "id",
+ "description": "The skill id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The skill's files",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillFileList"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/skills/{id}/files/{relativePath}": {
+ "get": {
+ "operationId": "getSkillFile",
+ "summary": "Get a skill's file",
+ "tags": [
+ "Skills"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "path",
+ "name": "id",
+ "description": "The skill id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ },
+ {
+ "in": "path",
+ "name": "relativePath",
+ "description": "The file path within the skill",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The file content",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillFileContent"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ "put": {
+ "operationId": "updateSkillFile",
+ "summary": "Create or update a skill's file",
+ "tags": [
+ "Skills"
+ ],
+ "security": [
+ {
+ "oidcBearer": []
+ }
+ ],
+ "parameters": [
+ {
+ "in": "path",
+ "name": "id",
+ "description": "The skill id",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ },
+ {
+ "in": "path",
+ "name": "relativePath",
+ "description": "The file path within the skill",
+ "schema": {
+ "type": "string"
+ },
+ "required": true
+ }
+ ],
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillFileUpdateRequest"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "The file was written",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillFileUpdated"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Invalid request, or a malformed JSON body",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/JsonParseError"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication failed",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/MessageError"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "Not found",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Error"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The bound account is being deleted",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AccountDeletionConflict"
+ }
+ }
+ }
+ },
+ "429": {
+ "description": "Too many file-write requests",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/MessageError"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "Internal server error",
+ "content": {
+ "application/json": {
+ "schema": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/Error"
+ },
+ {
+ "$ref": "#/components/schemas/ErrorMessage"
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "components": {
+ "securitySchemes": {
+ "oidcBearer": {
+ "type": "http",
+ "scheme": "bearer",
+ "bearerFormat": "JWT",
+ "description": "An OIDC access token, sent as a bearer token."
+ }
+ },
+ "schemas": {
+ "AgentCreateRequest": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "description": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "instructions": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "avatar": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "properties": {
+ "filepath": {
+ "type": "string"
+ },
+ "source": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "filepath",
+ "source"
+ ]
+ },
+ "model_parameters": {
+ "type": "object",
+ "additionalProperties": {}
+ },
+ "tools": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "default": []
+ },
+ "skills": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "skills_enabled": {
+ "type": "boolean"
+ },
+ "skill_authoring_enabled": {
+ "type": "boolean"
+ },
+ "skills_scope": {
+ "type": "string",
+ "enum": [
+ "all",
+ "selected",
+ "none"
+ ]
+ },
+ "memory_scope": {
+ "type": "string",
+ "enum": [
+ "user",
+ "agent"
+ ]
+ },
+ "agent_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "edges": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "from": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ ]
+ },
+ "to": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ ]
+ },
+ "description": {
+ "type": "string"
+ },
+ "edgeType": {
+ "type": "string",
+ "enum": [
+ "handoff",
+ "direct"
+ ]
+ },
+ "prompt": {
+ "type": "string"
+ },
+ "excludeResults": {
+ "type": "boolean"
+ },
+ "promptKey": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "from",
+ "to"
+ ]
+ }
+ },
+ "end_after_tools": {
+ "type": "boolean"
+ },
+ "hide_sequential_outputs": {
+ "type": "boolean"
+ },
+ "stateful_code_sessions": {
+ "type": "boolean"
+ },
+ "stateful_code_environment": {
+ "type": "string",
+ "enum": [
+ "user",
+ "agent-user",
+ "conversation"
+ ]
+ },
+ "code_environment_id": {
+ "type": "string",
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+ },
+ "code_workspace_id": {
+ "anyOf": [
+ {
+ "type": "string",
+ "const": ""
+ },
+ {
+ "type": "string",
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+ }
+ ]
+ },
+ "git_identity": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 128
+ },
+ "email": {
+ "type": "string",
+ "format": "email",
+ "maxLength": 254
+ }
+ },
+ "required": [
+ "name",
+ "email"
+ ]
+ },
+ "artifacts": {
+ "type": "string"
+ },
+ "recursion_limit": {
+ "type": "number"
+ },
+ "conversation_starters": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "tool_resources": {
+ "type": "object",
+ "properties": {
+ "image_edit": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "execute_code": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "file_search": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "vector_store_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "context": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "ocr": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ }
+ },
+ "tool_options": {
+ "type": "object",
+ "additionalProperties": {
+ "type": "object",
+ "properties": {
+ "defer_loading": {
+ "type": "boolean"
+ },
+ "allowed_callers": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "enum": [
+ "direct",
+ "code_execution"
+ ]
+ }
+ },
+ "run_in_background": {
+ "type": "boolean"
+ },
+ "describe_intent": {
+ "type": "boolean"
+ }
+ }
+ }
+ },
+ "subagents": {
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "type": "boolean"
+ },
+ "allowSelf": {
+ "type": "boolean"
+ },
+ "shareFiles": {
+ "type": "boolean"
+ },
+ "agent_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "graphs": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "minLength": 1
+ },
+ "name": {
+ "type": "string",
+ "minLength": 1
+ },
+ "description": {
+ "type": "string",
+ "minLength": 1
+ },
+ "agent_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "minItems": 1,
+ "maxItems": 32
+ },
+ "edges": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "from": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "minItems": 1
+ }
+ ]
+ },
+ "to": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "minItems": 1
+ }
+ ]
+ },
+ "description": {
+ "type": "string"
+ },
+ "edgeType": {
+ "type": "string",
+ "const": "direct"
+ },
+ "prompt": {
+ "type": "string"
+ },
+ "excludeResults": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "from",
+ "to",
+ "edgeType"
+ ],
+ "additionalProperties": false
+ }
+ },
+ "entry_agent_id": {
+ "type": "string"
+ },
+ "result_agent_id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description",
+ "agent_ids",
+ "edges",
+ "entry_agent_id",
+ "result_agent_id"
+ ]
+ }
+ }
+ }
+ },
+ "support_contact": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "email": {
+ "anyOf": [
+ {
+ "type": "string",
+ "const": ""
+ },
+ {
+ "type": "string",
+ "format": "email"
+ }
+ ]
+ }
+ }
+ },
+ "category": {
+ "type": "string"
+ },
+ "provider": {
+ "type": "string"
+ },
+ "model": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "provider",
+ "model"
+ ],
+ "additionalProperties": false
+ },
+ "AgentUpdateRequest": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "instructions": {
+ "type": "string"
+ },
+ "avatar": {
+ "type": "null"
+ },
+ "model_parameters": {
+ "type": "object",
+ "additionalProperties": {}
+ },
+ "tools": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "skills": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "skills_enabled": {
+ "type": "boolean"
+ },
+ "skill_authoring_enabled": {
+ "type": "boolean"
+ },
+ "skills_scope": {
+ "type": "string",
+ "enum": [
+ "all",
+ "selected",
+ "none"
+ ]
+ },
+ "memory_scope": {
+ "type": "string",
+ "enum": [
+ "user",
+ "agent"
+ ]
+ },
+ "agent_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "edges": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "from": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ ]
+ },
+ "to": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ ]
+ },
+ "description": {
+ "type": "string"
+ },
+ "edgeType": {
+ "type": "string",
+ "enum": [
+ "handoff",
+ "direct"
+ ]
+ },
+ "prompt": {
+ "type": "string"
+ },
+ "excludeResults": {
+ "type": "boolean"
+ },
+ "promptKey": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "from",
+ "to"
+ ]
+ }
+ },
+ "end_after_tools": {
+ "type": "boolean"
+ },
+ "hide_sequential_outputs": {
+ "type": "boolean"
+ },
+ "stateful_code_sessions": {
+ "type": "boolean"
+ },
+ "stateful_code_environment": {
+ "type": "string",
+ "enum": [
+ "user",
+ "agent-user",
+ "conversation"
+ ]
+ },
+ "code_environment_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+ },
+ "code_workspace_id": {
+ "anyOf": [
+ {
+ "type": "string",
+ "const": ""
+ },
+ {
+ "type": "string",
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+ }
+ ]
+ },
+ "git_identity": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "properties": {
+ "name": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 128
+ },
+ "email": {
+ "type": "string",
+ "format": "email",
+ "maxLength": 254
+ }
+ },
+ "required": [
+ "name",
+ "email"
+ ]
+ },
+ "artifacts": {
+ "type": "string"
+ },
+ "recursion_limit": {
+ "type": "number"
+ },
+ "conversation_starters": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "tool_resources": {
+ "type": "object",
+ "properties": {
+ "image_edit": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "execute_code": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "file_search": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "vector_store_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "context": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "ocr": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ }
+ },
+ "tool_options": {
+ "type": "object",
+ "additionalProperties": {
+ "type": "object",
+ "properties": {
+ "defer_loading": {
+ "type": "boolean"
+ },
+ "allowed_callers": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "enum": [
+ "direct",
+ "code_execution"
+ ]
+ }
+ },
+ "run_in_background": {
+ "type": "boolean"
+ },
+ "describe_intent": {
+ "type": "boolean"
+ }
+ }
+ }
+ },
+ "subagents": {
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "type": "boolean"
+ },
+ "allowSelf": {
+ "type": "boolean"
+ },
+ "shareFiles": {
+ "type": "boolean"
+ },
+ "agent_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "graphs": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "minLength": 1
+ },
+ "name": {
+ "type": "string",
+ "minLength": 1
+ },
+ "description": {
+ "type": "string",
+ "minLength": 1
+ },
+ "agent_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "minItems": 1,
+ "maxItems": 32
+ },
+ "edges": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "from": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "minItems": 1
+ }
+ ]
+ },
+ "to": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "minItems": 1
+ }
+ ]
+ },
+ "description": {
+ "type": "string"
+ },
+ "edgeType": {
+ "type": "string",
+ "const": "direct"
+ },
+ "prompt": {
+ "type": "string"
+ },
+ "excludeResults": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "from",
+ "to",
+ "edgeType"
+ ],
+ "additionalProperties": false
+ }
+ },
+ "entry_agent_id": {
+ "type": "string"
+ },
+ "result_agent_id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description",
+ "agent_ids",
+ "edges",
+ "entry_agent_id",
+ "result_agent_id"
+ ]
+ }
+ }
+ }
+ },
+ "support_contact": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "email": {
+ "anyOf": [
+ {
+ "type": "string",
+ "const": ""
+ },
+ {
+ "type": "string",
+ "format": "email"
+ }
+ ]
+ }
+ }
+ },
+ "category": {
+ "type": "string"
+ },
+ "provider": {
+ "type": "string"
+ },
+ "model": {
+ "type": "string"
+ }
+ },
+ "additionalProperties": false
+ },
+ "Agent": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "description": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "instructions": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "avatar": {
+ "anyOf": [
+ {
+ "type": "object",
+ "properties": {
+ "filepath": {
+ "type": "string"
+ },
+ "source": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "filepath",
+ "source"
+ ]
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "model_parameters": {
+ "type": "object",
+ "additionalProperties": {}
+ },
+ "tools": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "skills": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "skills_enabled": {
+ "type": "boolean"
+ },
+ "skill_authoring_enabled": {
+ "type": "boolean"
+ },
+ "skills_scope": {
+ "type": "string",
+ "enum": [
+ "all",
+ "selected",
+ "none"
+ ]
+ },
+ "memory_scope": {
+ "type": "string",
+ "enum": [
+ "user",
+ "agent"
+ ]
+ },
+ "agent_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "edges": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "from": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ ]
+ },
+ "to": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ ]
+ },
+ "description": {
+ "type": "string"
+ },
+ "edgeType": {
+ "type": "string",
+ "enum": [
+ "handoff",
+ "direct"
+ ]
+ },
+ "prompt": {
+ "type": "string"
+ },
+ "excludeResults": {
+ "type": "boolean"
+ },
+ "promptKey": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "from",
+ "to"
+ ]
+ }
+ },
+ "end_after_tools": {
+ "type": "boolean"
+ },
+ "hide_sequential_outputs": {
+ "type": "boolean"
+ },
+ "stateful_code_sessions": {
+ "type": "boolean"
+ },
+ "stateful_code_environment": {
+ "type": "string",
+ "enum": [
+ "user",
+ "agent-user",
+ "conversation"
+ ]
+ },
+ "code_environment_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+ },
+ "code_workspace_id": {
+ "anyOf": [
+ {
+ "type": "string",
+ "const": ""
+ },
+ {
+ "type": "string",
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+ }
+ ]
+ },
+ "git_identity": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "properties": {
+ "name": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 128
+ },
+ "email": {
+ "type": "string",
+ "format": "email",
+ "maxLength": 254
+ }
+ },
+ "required": [
+ "name",
+ "email"
+ ]
+ },
+ "artifacts": {
+ "type": "string"
+ },
+ "recursion_limit": {
+ "type": "number"
+ },
+ "conversation_starters": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "tool_resources": {
+ "type": "object",
+ "properties": {
+ "image_edit": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "execute_code": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "file_search": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "vector_store_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "context": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "ocr": {
+ "type": "object",
+ "properties": {
+ "file_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ }
+ },
+ "tool_options": {
+ "type": "object",
+ "additionalProperties": {
+ "type": "object",
+ "properties": {
+ "defer_loading": {
+ "type": "boolean"
+ },
+ "allowed_callers": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "enum": [
+ "direct",
+ "code_execution"
+ ]
+ }
+ },
+ "run_in_background": {
+ "type": "boolean"
+ },
+ "describe_intent": {
+ "type": "boolean"
+ }
+ }
+ }
+ },
+ "subagents": {
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "type": "boolean"
+ },
+ "allowSelf": {
+ "type": "boolean"
+ },
+ "agent_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "graphs": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "agent_ids": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "edges": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "from": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ ]
+ },
+ "to": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ }
+ ]
+ },
+ "description": {
+ "type": "string"
+ },
+ "edgeType": {
+ "type": "string",
+ "const": "direct"
+ },
+ "prompt": {
+ "type": "string"
+ },
+ "excludeResults": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "from",
+ "to",
+ "edgeType"
+ ],
+ "additionalProperties": false
+ }
+ },
+ "entry_agent_id": {
+ "type": "string"
+ },
+ "result_agent_id": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description",
+ "agent_ids",
+ "edges",
+ "entry_agent_id",
+ "result_agent_id"
+ ],
+ "additionalProperties": false
+ }
+ }
+ },
+ "additionalProperties": false
+ },
+ "support_contact": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "email": {
+ "anyOf": [
+ {
+ "type": "string",
+ "const": ""
+ },
+ {
+ "type": "string",
+ "format": "email"
+ }
+ ]
+ }
+ }
+ },
+ "category": {
+ "type": "string"
+ },
+ "provider": {
+ "type": "string"
+ },
+ "model": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "type": "string",
+ "minLength": 1
+ },
+ "version": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "createdAt": {
+ "type": "string",
+ "format": "date-time"
+ },
+ "updatedAt": {
+ "type": "string",
+ "format": "date-time"
+ }
+ },
+ "required": [
+ "provider",
+ "model",
+ "id",
+ "version",
+ "createdAt",
+ "updatedAt"
+ ],
+ "additionalProperties": false
+ },
+ "AgentList": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "list"
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/Agent"
+ }
+ },
+ "first_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "last_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "has_more": {
+ "type": "boolean"
+ },
+ "after": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 1,
+ "maxLength": 512
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more",
+ "after"
+ ],
+ "additionalProperties": false
+ },
+ "AgentDeleted": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 1
+ },
+ "deleted": {
+ "type": "boolean",
+ "const": true
+ }
+ },
+ "required": [
+ "id",
+ "deleted"
+ ],
+ "additionalProperties": false
+ },
+ "AgentFile": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "const": "agent.file"
+ },
+ "filename": {
+ "type": "string"
+ },
+ "bytes": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "mime_type": {
+ "type": "string"
+ },
+ "purposes": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "created_at": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "format": "date-time"
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "filename",
+ "bytes",
+ "mime_type",
+ "purposes",
+ "created_at"
+ ]
+ },
+ "AgentFileList": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "list"
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/AgentFile"
+ }
+ }
+ },
+ "required": [
+ "object",
+ "data"
+ ]
+ },
+ "AgentFileDeleted": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "deleted": {
+ "type": "boolean",
+ "const": true
+ }
+ },
+ "required": [
+ "id",
+ "deleted"
+ ]
+ },
+ "Error": {
+ "type": "object",
+ "properties": {
+ "error": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "string",
+ "enum": [
+ "invalid_request",
+ "not_found",
+ "permission_denied",
+ "internal_error",
+ "conflict"
+ ]
+ },
+ "message": {
+ "type": "string"
+ },
+ "details": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "path": {
+ "type": "array",
+ "items": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "number"
+ }
+ ]
+ }
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "path",
+ "message"
+ ],
+ "additionalProperties": false
+ }
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "additionalProperties": false
+ }
+ },
+ "required": [
+ "error"
+ ],
+ "additionalProperties": false
+ },
+ "SkillFrontmatterValue": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "number"
+ },
+ {
+ "type": "boolean"
+ },
+ {
+ "type": "null"
+ },
+ {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SkillFrontmatterValue"
+ }
+ },
+ {
+ "type": "object",
+ "additionalProperties": {
+ "$ref": "#/components/schemas/SkillFrontmatterValue"
+ }
+ }
+ ]
+ },
+ "Skill": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "displayTitle": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "category": {
+ "type": "string"
+ },
+ "alwaysApply": {
+ "type": "boolean"
+ },
+ "id": {
+ "type": "string",
+ "pattern": "^[a-f\\d]{24}$"
+ },
+ "version": {
+ "type": "integer",
+ "exclusiveMinimum": 0
+ },
+ "fileCount": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "disableModelInvocation": {
+ "type": "boolean"
+ },
+ "userInvocable": {
+ "type": "boolean"
+ },
+ "allowedTools": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "createdAt": {
+ "type": "string",
+ "format": "date-time"
+ },
+ "updatedAt": {
+ "type": "string",
+ "format": "date-time"
+ },
+ "body": {
+ "type": "string"
+ },
+ "frontmatter": {
+ "type": "object",
+ "additionalProperties": {
+ "$ref": "#/components/schemas/SkillFrontmatterValue"
+ }
+ }
+ },
+ "required": [
+ "name",
+ "description",
+ "id",
+ "version",
+ "fileCount",
+ "createdAt",
+ "updatedAt",
+ "body"
+ ]
+ },
+ "SkillList": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "list"
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "displayTitle": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "category": {
+ "type": "string"
+ },
+ "alwaysApply": {
+ "type": "boolean"
+ },
+ "id": {
+ "type": "string",
+ "pattern": "^[a-f\\d]{24}$"
+ },
+ "version": {
+ "type": "integer",
+ "exclusiveMinimum": 0
+ },
+ "fileCount": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "disableModelInvocation": {
+ "type": "boolean"
+ },
+ "userInvocable": {
+ "type": "boolean"
+ },
+ "allowedTools": {
+ "type": "array",
+ "items": {
+ "type": "string"
+ }
+ },
+ "createdAt": {
+ "type": "string",
+ "format": "date-time"
+ },
+ "updatedAt": {
+ "type": "string",
+ "format": "date-time"
+ }
+ },
+ "required": [
+ "name",
+ "description",
+ "id",
+ "version",
+ "fileCount",
+ "createdAt",
+ "updatedAt"
+ ]
+ }
+ },
+ "first_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "last_id": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "has_more": {
+ "type": "boolean"
+ },
+ "after": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more",
+ "after"
+ ]
+ },
+ "SkillUpdateRequest": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string"
+ },
+ "displayTitle": {
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "category": {
+ "type": "string"
+ },
+ "alwaysApply": {
+ "type": "boolean"
+ },
+ "body": {
+ "type": "string"
+ },
+ "frontmatter": {
+ "type": "object",
+ "additionalProperties": {
+ "$ref": "#/components/schemas/SkillFrontmatterValue"
+ }
+ },
+ "expectedVersion": {
+ "type": "integer",
+ "exclusiveMinimum": 0
+ }
+ },
+ "required": [
+ "expectedVersion"
+ ],
+ "additionalProperties": false,
+ "minProperties": 2
+ },
+ "SkillFile": {
+ "type": "object",
+ "properties": {
+ "relativePath": {
+ "type": "string"
+ },
+ "filename": {
+ "type": "string"
+ },
+ "mimeType": {
+ "type": "string"
+ },
+ "bytes": {
+ "type": "integer",
+ "minimum": 0
+ }
+ },
+ "required": [
+ "relativePath",
+ "filename",
+ "mimeType",
+ "bytes"
+ ]
+ },
+ "SkillFileList": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "const": "list"
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SkillFile"
+ }
+ }
+ },
+ "required": [
+ "object",
+ "data"
+ ]
+ },
+ "SkillFileContent": {
+ "type": "object",
+ "properties": {
+ "relativePath": {
+ "type": "string"
+ },
+ "filename": {
+ "type": "string"
+ },
+ "mimeType": {
+ "type": "string"
+ },
+ "bytes": {
+ "type": "integer",
+ "minimum": 0
+ },
+ "content": {
+ "type": "string"
+ },
+ "isBinary": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "relativePath",
+ "filename",
+ "mimeType",
+ "bytes",
+ "isBinary"
+ ]
+ },
+ "SkillFileUpdateRequest": {
+ "type": "object",
+ "properties": {
+ "content": {
+ "type": "string",
+ "maxLength": 1048576,
+ "description": "The file content. The accepted maximum is 1 MiB (1,048,576 bytes) of UTF-8-encoded content. The limit is measured in bytes, not characters, so non-ASCII content reaches it at fewer characters."
+ }
+ },
+ "required": [
+ "content"
+ ],
+ "additionalProperties": false
+ },
+ "SkillFileUpdated": {
+ "type": "object",
+ "properties": {
+ "relativePath": {
+ "type": "string"
+ },
+ "bytes": {
+ "type": "integer",
+ "minimum": 0
+ }
+ },
+ "required": [
+ "relativePath",
+ "bytes"
+ ]
+ },
+ "ErrorMessage": {
+ "type": "object",
+ "properties": {
+ "error": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "error"
+ ],
+ "additionalProperties": false
+ },
+ "AccountDeletionConflict": {
+ "type": "object",
+ "properties": {
+ "error": {
+ "type": "string"
+ },
+ "code": {
+ "type": "string",
+ "const": "ACCOUNT_DELETION_IN_PROGRESS"
+ }
+ },
+ "required": [
+ "error",
+ "code"
+ ],
+ "additionalProperties": false
+ },
+ "MessageError": {
+ "type": "object",
+ "properties": {
+ "message": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "message"
+ ],
+ "additionalProperties": false
+ },
+ "JsonParseError": {
+ "type": "object",
+ "properties": {
+ "error": {
+ "type": "string",
+ "const": "Invalid JSON format"
+ },
+ "message": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "error",
+ "message"
+ ],
+ "additionalProperties": false
+ }
+ }
+ }
+}
diff --git a/packages/api/package.json b/packages/api/package.json
index 9529ee0ff2..1faf92ab1d 100644
--- a/packages/api/package.json
+++ b/packages/api/package.json
@@ -27,10 +27,11 @@
},
"scripts": {
"clean": "rimraf dist",
- "build": "npm run clean && tsdown",
- "build:dev": "npm run clean && tsdown",
- "build:watch": "tsdown --watch",
- "build:watch:prod": "tsdown --watch",
+ "build": "npm run clean && tsdown && npm run openapi:copy",
+ "build:dev": "npm run clean && tsdown && npm run openapi:copy",
+ "build:watch": "npm run openapi:copy && tsdown --watch",
+ "build:watch:prod": "npm run openapi:copy && tsdown --watch",
+ "openapi:copy": "node -e \"const fs=require('fs');fs.mkdirSync('dist',{recursive:true});fs.copyFileSync('openapi/agents.openapi.json','dist/agents.openapi.json')\"",
"test": "jest --coverage --watch --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.|__tests__/helpers/|\\.*manual\\.spec\\.\"",
"test:ci": "jest --coverage --ci --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.|__tests__/helpers/|\\.*manual\\.spec\\.\"",
"test:cache-integration:core": "jest --testPathPatterns=\"src/(cache|middleware)/.*\\.cache_integration\\.(spec|test)\\.ts$\" --coverage=false",
@@ -43,8 +44,10 @@
"test:agents-integration": "jest --testPathPatterns=\"src/agents/.*\\.integration\\.spec\\.ts$\" --coverage=false --runInBand --forceExit",
"verify": "npm run test:ci",
"b:clean": "bun run rimraf dist",
- "b:build": "bun run b:clean && bun run tsdown",
- "b:build:dev": "bun run b:clean && bun run tsdown",
+ "b:build": "bun run b:clean && bun run tsdown && bun run openapi:copy",
+ "b:build:dev": "bun run b:clean && bun run tsdown && bun run openapi:copy",
+ "openapi:generate": "cross-env TS_NODE_PROJECT=tsconfig.openapi.json ts-node -r tsconfig-paths/register src/openapi/generate.ts --write",
+ "openapi:check": "cross-env TS_NODE_PROJECT=tsconfig.openapi.json ts-node -r tsconfig-paths/register src/openapi/generate.ts --check",
"start:everything-sse": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/examples/everything/sse.ts",
"start:everything": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/demo/everything.ts",
"start:filesystem": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/demo/filesystem.ts",
@@ -97,7 +100,8 @@
"typescript": "^5.9.3",
"winston": "^3.17.0",
"xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
- "yauzl": "^3.2.1"
+ "yauzl": "^3.2.1",
+ "zod-openapi": "^4.2.4"
},
"publishConfig": {
"registry": "https://registry.npmjs.org/"
diff --git a/packages/api/src/agents/management.ts b/packages/api/src/agents/management.ts
index f45e9bc6d1..1573243b5e 100644
--- a/packages/api/src/agents/management.ts
+++ b/packages/api/src/agents/management.ts
@@ -181,7 +181,8 @@ export const agentManagementResponseSchema: z.ZodType<AgentManagementResponse> =
})
.strict();
-export const agentManagementListResponseSchema: z.ZodType<AgentManagementListResponse> = z
+/** The list envelope as a plain object, so the OpenAPI contract can reuse it and override only `data`. */
+export const agentManagementListEnvelopeSchema: z.ZodType<AgentManagementListResponse> = z
.object({
object: z.literal('list'),
data: z.array(agentManagementResponseSchema),
@@ -190,8 +191,10 @@ export const agentManagementListResponseSchema: z.ZodType<AgentManagementListRes
has_more: z.boolean(),
after: agentManagementCursorSchema.nullable(),
})
- .strict()
- .superRefine(({ has_more, after }, context) => {
+ .strict();
+
+export const agentManagementListResponseSchema: z.ZodType<AgentManagementListResponse> =
+ agentManagementListEnvelopeSchema.superRefine(({ has_more, after }, context) => {
if (has_more !== (after != null)) {
context.addIssue({
code: z.ZodIssueCode.custom,
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
index a1bb4dd789..3e71702fbc 100644
--- a/packages/api/src/index.ts
+++ b/packages/api/src/index.ts
@@ -121,6 +121,9 @@ export * from './stream';
export { memoryDiagnostics } from './utils/memory';
/* RUM */
export * from './rum/proxy';
+/* OpenAPI */
+export { createOpenApiRouter } from './openapi/router';
+export type { OpenApiRouterDeps } from './openapi/router';
/* types */
export type * from './mcp/types';
export type * from './flow/types';
diff --git a/packages/api/src/openapi/adapter.ts b/packages/api/src/openapi/adapter.ts
new file mode 100644
index 0000000000..846ef8fcb3
--- /dev/null
+++ b/packages/api/src/openapi/adapter.ts
@@ -0,0 +1,165 @@
+import { z } from 'zod';
+import { createDocument } from 'zod-openapi';
+import type { ZodTypeAny } from 'zod';
+
+/**
+ * The seam. This is the only file that imports the Zod-to-OpenAPI converter.
+ * If we replace the converter, only this file changes.
+ */
+
+export type SecurityScheme = {
+ type: string;
+ scheme?: string;
+ bearerFormat?: string;
+ description?: string;
+};
+
+/** A media-type object written by hand, for requests or responses that have no Zod schema. */
+export type RawContent = Record<string, { schema: Record<string, unknown> }>;
+
+export type ResponseContract = {
+ status: number;
+ description: string /** A Zod schema. When it is also listed in `componentSchemas`, the document uses a `$ref`. */;
+ schema?: ZodTypeAny;
+ /** A hand-written media-type object, used when there is no Zod schema. */
+ content?: RawContent;
+};
+
+export type EndpointContract = {
+ operationId: string;
+ method: 'get' | 'post' | 'patch' | 'delete' | 'put';
+ /** OpenAPI-style path, relative to the server base, e.g. `/agents/{id}`. */
+ path: string;
+ tags: string[];
+ summary: string;
+ description?: string;
+ /** Names of the security schemes that apply to this endpoint. */
+ security: string[];
+ pathParams?: { name: string; description?: string }[];
+ /** An object schema whose fields become query parameters. */
+ query?: ZodTypeAny;
+ /** A JSON request body. When it is also listed in `componentSchemas`, the document uses a `$ref`. */
+ body?: ZodTypeAny;
+ /** A hand-written request body, used for multipart uploads. */
+ rawBody?: { description?: string; required?: boolean; content: RawContent };
+ responses: ResponseContract[];
+};
+
+export type OpenApiInput = {
+ info: { title: string; version: string; description?: string };
+ servers: { url: string; description?: string }[];
+ securitySchemes: Record<string, SecurityScheme>;
+ /** Named schemas that become reusable `#/components/schemas` entries. */
+ componentSchemas: Record<string, ZodTypeAny>;
+ /**
+ * Extra OpenAPI keywords merged into a generated component schema, keyed by component name.
+ * Use this for constraints the converter cannot express, such as an object-level `.refine()`.
+ */
+ componentSchemaOverrides?: Record<string, Record<string, unknown>>;
+ contracts: EndpointContract[];
+};
+
+function buildResponses(responses: ResponseContract[]): Record<string, unknown> {
+ const result: Record<string, unknown> = {};
+ for (const response of responses) {
+ if (response.content) {
+ result[response.status] = { description: response.description, content: response.content };
+ continue;
+ }
+ if (response.schema) {
+ result[response.status] = {
+ description: response.description,
+ content: { 'application/json': { schema: response.schema } },
+ };
+ continue;
+ }
+ result[response.status] = { description: response.description };
+ }
+ return result;
+}
+
+function buildOperation(contract: EndpointContract): Record<string, unknown> {
+ const operation: Record<string, unknown> = {
+ operationId: contract.operationId,
+ summary: contract.summary,
+ tags: contract.tags,
+ security: contract.security.map((name) => ({ [name]: [] })),
+ responses: buildResponses(contract.responses),
+ };
+ if (contract.description) {
+ operation.description = contract.description;
+ }
+ const requestParams: Record<string, unknown> = {};
+ if (contract.pathParams?.length) {
+ requestParams.path = z.object(
+ Object.fromEntries(
+ contract.pathParams.map((param) => [
+ param.name,
+ param.description ? z.string().describe(param.description) : z.string(),
+ ]),
+ ),
+ );
+ }
+ if (contract.query) {
+ requestParams.query = contract.query;
+ }
+ if (Object.keys(requestParams).length > 0) {
+ operation.requestParams = requestParams;
+ }
+ if (contract.rawBody) {
+ operation.requestBody = {
+ description: contract.rawBody.description,
+ required: contract.rawBody.required ?? false,
+ content: contract.rawBody.content,
+ };
+ } else if (contract.body) {
+ operation.requestBody = {
+ required: true,
+ content: { 'application/json': { schema: contract.body } },
+ };
+ }
+ return operation;
+}
+
+/** Merge extra OpenAPI keywords into generated component schemas the converter built too loosely. */
+function applyComponentSchemaOverrides(
+ document: Record<string, unknown>,
+ overrides?: Record<string, Record<string, unknown>>,
+): void {
+ if (!overrides) {
+ return;
+ }
+ const components = document.components as
+ | { schemas?: Record<string, Record<string, unknown>> }
+ | undefined;
+ const schemas = components?.schemas;
+ if (!schemas) {
+ return;
+ }
+ for (const [name, extra] of Object.entries(overrides)) {
+ if (schemas[name]) {
+ Object.assign(schemas[name], extra);
+ }
+ }
+}
+
+export function buildOpenApiDocument(input: OpenApiInput): Record<string, unknown> {
+ const paths: Record<string, Record<string, unknown>> = {};
+ for (const contract of input.contracts) {
+ paths[contract.path] ??= {};
+ paths[contract.path][contract.method] = buildOperation(contract);
+ }
+ const spec = {
+ openapi: '3.1.0',
+ info: input.info,
+ servers: input.servers,
+ components: {
+ securitySchemes: input.securitySchemes,
+ schemas: input.componentSchemas,
+ },
+ paths,
+ } as unknown as Parameters<typeof createDocument>[0];
+ const document = createDocument(spec) as unknown as Record<string, unknown>;
+ applyComponentSchemaOverrides(document, input.componentSchemaOverrides);
+ return document;
+}
diff --git a/packages/api/src/openapi/agents.ts b/packages/api/src/openapi/agents.ts
new file mode 100644
index 0000000000..85c77b5c15
--- /dev/null
+++ b/packages/api/src/openapi/agents.ts
@@ -0,0 +1,260 @@
+import { z } from 'zod';
+import type { ZodTypeAny } from 'zod';
+import type { EndpointContract } from './adapter';
+import {
+ agentManagementCreateSchema,
+ agentManagementUpdateSchema,
+ agentManagementListSchema,
+ agentManagementResponseSchema,
+ agentManagementListEnvelopeSchema,
+ agentManagementDeleteResponseSchema,
+ agentManagementErrorSchema,
+} from '../agents/management';
+import {
+ errorMessageResponseSchema,
+ accountDeletionResponseSchema,
+ messageResponseSchema,
+ jsonParseErrorSchema,
+} from './errors';
+
+const TAG = 'Agents';
+const SECURITY = ['oidcBearer'];
+
+/**
+ * `edges[].prompt` accepts a string or a function at runtime (see agents/validation.ts).
+ * OpenAPI cannot express a function, so the document uses a string-only variant of the edge.
+ * This changes the document only. The runtime schema is untouched.
+ */
+const documentedEdgeSchema = z.object({
+ from: z.union([z.string(), z.array(z.string())]),
+ to: z.union([z.string(), z.array(z.string())]),
+ description: z.string().optional(),
+ edgeType: z.enum(['handoff', 'direct']).optional(),
+ prompt: z.string().optional(),
+ excludeResults: z.boolean().optional(),
+ promptKey: z.string().optional(),
+});
+
+/**
+ * Replace only the `edges` field for the document. The schemas are `ZodObject` at runtime
+ * (built with `.extend(...).strict()`), but their exported type is the wider `ZodType`, so
+ * one cast is needed to reach `.extend`.
+ */
+function withDocumentedEdges(schema: ZodTypeAny): ZodTypeAny {
+ return (schema as unknown as z.AnyZodObject).extend({
+ edges: z.array(documentedEdgeSchema).optional(),
+ });
+}
+
+const agentCreateRequestSchema = withDocumentedEdges(agentManagementCreateSchema);
+const agentUpdateRequestSchema = withDocumentedEdges(agentManagementUpdateSchema);
+const agentResponseSchema = withDocumentedEdges(agentManagementResponseSchema);
+
+/**
+ * Reuse the enforced list envelope; override only `data` with the documented-edge agent.
+ * The envelope is exported as `ZodType`, so reach `.extend` the same way `withDocumentedEdges` does.
+ */
+const agentListResponseSchema = (
+ agentManagementListEnvelopeSchema as unknown as z.AnyZodObject
+).extend({
+ data: z.array(agentResponseSchema),
+});
+
+/** The file endpoints are not validated with Zod at runtime; these schemas describe their hand-built responses. */
+const agentFileSchema = z.object({
+ id: z.string(),
+ object: z.literal('agent.file'),
+ filename: z.string(),
+ bytes: z.number().int().nonnegative(),
+ mime_type: z.string(),
+ purposes: z.array(z.string()),
+ created_at: z.string().datetime().nullable(),
+});
+const agentFileListSchema = z.object({
+ object: z.literal('list'),
+ data: z.array(agentFileSchema),
+});
+const agentFileDeletedSchema = z.object({
+ id: z.string(),
+ deleted: z.literal(true),
+});
+
+export const agentComponentSchemas: Record<string, ZodTypeAny> = {
+ AgentCreateRequest: agentCreateRequestSchema,
+ AgentUpdateRequest: agentUpdateRequestSchema,
+ Agent: agentResponseSchema,
+ AgentList: agentListResponseSchema,
+ AgentDeleted: agentManagementDeleteResponseSchema,
+ AgentFile: agentFileSchema,
+ AgentFileList: agentFileListSchema,
+ AgentFileDeleted: agentFileDeletedSchema,
+ Error: agentManagementErrorSchema,
+};
+
+const errorResponses = [
+ {
+ status: 400,
+ description: 'Invalid request, or a malformed JSON body',
+ schema: z.union([agentManagementErrorSchema, jsonParseErrorSchema]),
+ },
+ { status: 401, description: 'Authentication failed', schema: errorMessageResponseSchema },
+ {
+ status: 403,
+ description: 'Permission denied, the caller is banned, or the request fails tenant isolation',
+ schema: z.union([
+ agentManagementErrorSchema,
+ messageResponseSchema,
+ errorMessageResponseSchema,
+ ]),
+ },
+ { status: 404, description: 'Not found', schema: agentManagementErrorSchema },
+ {
+ status: 409,
+ description: 'The bound account is being deleted',
+ schema: accountDeletionResponseSchema,
+ },
+ {
+ status: 500,
+ description: 'Internal server error',
+ schema: z.union([agentManagementErrorSchema, errorMessageResponseSchema]),
+ },
+];
+
+export const agentContracts: EndpointContract[] = [
+ {
+ operationId: 'createAgent',
+ method: 'post',
+ path: '/agents',
+ tags: [TAG],
+ summary: 'Create an agent',
+ security: SECURITY,
+ body: agentCreateRequestSchema,
+ responses: [
+ { status: 201, description: 'The created agent', schema: agentResponseSchema },
+ ...errorResponses,
+ ],
+ },
+ {
+ operationId: 'listAgents',
+ method: 'get',
+ path: '/agents',
+ tags: [TAG],
+ summary: 'List agents',
+ security: SECURITY,
+ query: agentManagementListSchema,
+ responses: [
+ { status: 200, description: 'A page of agents', schema: agentListResponseSchema },
+ ...errorResponses,
+ ],
+ },
+ {
+ operationId: 'getAgent',
+ method: 'get',
+ path: '/agents/{id}',
+ tags: [TAG],
+ summary: 'Get an agent',
+ security: SECURITY,
+ pathParams: [{ name: 'id', description: 'The agent id' }],
+ responses: [
+ { status: 200, description: 'The agent', schema: agentResponseSchema },
+ ...errorResponses,
+ ],
+ },
+ {
+ operationId: 'updateAgent',
+ method: 'patch',
+ path: '/agents/{id}',
+ tags: [TAG],
+ summary: 'Update an agent',
+ security: SECURITY,
+ pathParams: [{ name: 'id', description: 'The agent id' }],
+ body: agentUpdateRequestSchema,
+ responses: [
+ { status: 200, description: 'The updated agent', schema: agentResponseSchema },
+ ...errorResponses,
+ ],
+ },
+ {
+ operationId: 'deleteAgent',
+ method: 'delete',
+ path: '/agents/{id}',
+ tags: [TAG],
+ summary: 'Delete an agent',
+ security: SECURITY,
+ pathParams: [{ name: 'id', description: 'The agent id' }],
+ responses: [
+ {
+ status: 200,
+ description: 'The agent was deleted',
+ schema: agentManagementDeleteResponseSchema,
+ },
+ ...errorResponses,
+ ],
+ },
+ {
+ operationId: 'uploadAgentFile',
+ method: 'post',
+ path: '/agents/{id}/files',
+ tags: [TAG],
+ summary: 'Upload a file to an agent',
+ security: SECURITY,
+ pathParams: [{ name: 'id', description: 'The agent id' }],
+ rawBody: {
+ required: true,
+ content: {
+ 'multipart/form-data': {
+ schema: {
+ type: 'object',
+ required: ['file', 'purpose'],
+ properties: {
+ file: { type: 'string', format: 'binary' },
+ purpose: {
+ type: 'string',
+ enum: ['file_search', 'execute_code', 'context'],
+ description: 'The tool resource the file is uploaded for.',
+ },
+ },
+ },
+ },
+ },
+ },
+ responses: [
+ { status: 200, description: 'The uploaded file', schema: agentFileSchema },
+ ...errorResponses,
+ {
+ status: 429,
+ description: 'Too many upload requests',
+ schema: agentManagementErrorSchema,
+ },
+ ],
+ },
+ {
+ operationId: 'listAgentFiles',
+ method: 'get',
+ path: '/agents/{id}/files',
+ tags: [TAG],
+ summary: "List an agent's files",
+ security: SECURITY,
+ pathParams: [{ name: 'id', description: 'The agent id' }],
+ responses: [
+ { status: 200, description: "The agent's files", schema: agentFileListSchema },
+ ...errorResponses,
+ ],
+ },
+ {
+ operationId: 'deleteAgentFile',
+ method: 'delete',
+ path: '/agents/{id}/files/{fileId}',
+ tags: [TAG],
+ summary: "Delete an agent's file",
+ security: SECURITY,
+ pathParams: [
+ { name: 'id', description: 'The agent id' },
+ { name: 'fileId', description: 'The file id' },
+ ],
+ responses: [
+ { status: 200, description: 'The file was deleted', schema: agentFileDeletedSchema },
+ ...errorResponses,
+ ],
+ },
+];
diff --git a/packages/api/src/openapi/document.ts b/packages/api/src/openapi/document.ts
new file mode 100644
index 0000000000..e314962e0a
--- /dev/null
+++ b/packages/api/src/openapi/document.ts
@@ -0,0 +1,28 @@
+import { securitySchemes, componentSchemas, componentSchemaOverrides, contracts } from './registry';
+import { buildOpenApiDocument } from './adapter';
+
+/** Stable document version, independent of the package version, so the artifact does not churn. */
+const DOCUMENT_VERSION = '0.1.0';
+
+/** Build the OpenAPI 3.1 document for the public agent and skill management endpoints. */
+export function buildAgentsOpenApiDocument(): Record<string, unknown> {
+ return buildOpenApiDocument({
+ info: {
+ title: 'LibreChat Agents API',
+ version: DOCUMENT_VERSION,
+ description:
+ 'The public agent and skill management endpoints of the LibreChat Agents API. This API is in beta and may change.',
+ },
+ servers: [
+ {
+ url: 'agents/v1',
+ description:
+ 'Relative to where this document is served (`/api/openapi.json`), so it resolves under any deployment base path.',
+ },
+ ],
+ securitySchemes,
+ componentSchemas,
+ componentSchemaOverrides,
+ contracts,
+ });
+}
diff --git a/packages/api/src/openapi/errors.ts b/packages/api/src/openapi/errors.ts
new file mode 100644
index 0000000000..ce08670741
--- /dev/null
+++ b/packages/api/src/openapi/errors.ts
@@ -0,0 +1,35 @@
+import { z } from 'zod';
+
+/**
+ * The flat `{ error }` envelope the auth middleware sends for 401 (`{ error: 'Unauthorized' }`)
+ * and for its own 500 (`{ error: 'Internal server error' }`). One field, distinct from the nested
+ * `agentManagementErrorSchema`.
+ */
+export const errorMessageResponseSchema: z.ZodType<{ error: string }> = z
+ .object({ error: z.string() })
+ .strict();
+
+/**
+ * When the bound account is being deleted, the auth middleware sends 409 with a flat
+ * `{ error, code: 'ACCOUNT_DELETION_IN_PROGRESS' }` body. The code is a fixed discriminator.
+ */
+export const accountDeletionResponseSchema: z.ZodType<{
+ error: string;
+ code: 'ACCOUNT_DELETION_IN_PROGRESS';
+}> = z.object({ error: z.string(), code: z.literal('ACCOUNT_DELETION_IN_PROGRESS') }).strict();
+
+/**
+ * The ban middleware (403) and the default file-upload limiter (429) send a flat `{ message }`
+ * body, distinct from the other error shapes.
+ */
+export const messageResponseSchema: z.ZodType<{ message: string }> = z
+ .object({ message: z.string() })
+ .strict();
+
+/**
+ * The global JSON body parser runs before these routes and, on malformed JSON, returns 400 with
+ * a flat `{ error: 'Invalid JSON format', message }` body. The `error` field is a fixed discriminator.
+ */
+export const jsonParseErrorSchema: z.ZodType<{ error: 'Invalid JSON format'; message: string }> = z
+ .object({ error: z.literal('Invalid JSON format'), message: z.string() })
+ .strict();
diff --git a/packages/api/src/openapi/generate.ts b/packages/api/src/openapi/generate.ts
new file mode 100644
index 0000000000..c6f85e3fc6
--- /dev/null
+++ b/packages/api/src/openapi/generate.ts
@@ -0,0 +1,38 @@
+import fs from 'fs';
+import path from 'path';
+import { buildAgentsOpenApiDocument } from './document';
+
+/** Run from the package root (`npm run -w @librechat/api openapi:...`), so cwd is packages/api. */
+const SPEC_PATH = path.resolve(process.cwd(), 'openapi', 'agents.openapi.json');
+
+function render(): string {
+ return JSON.stringify(buildAgentsOpenApiDocument(), null, 2) + '\n';
+}
+
+function write(): void {
+ const json = render();
+ fs.mkdirSync(path.dirname(SPEC_PATH), { recursive: true });
+ fs.writeFileSync(SPEC_PATH, json);
+ console.log(`Wrote ${SPEC_PATH}`);
+}
+
+function check(): void {
+ const json = render();
+ const existing = fs.existsSync(SPEC_PATH) ? fs.readFileSync(SPEC_PATH, 'utf8') : '';
+ if (existing !== json) {
+ console.error(
+ 'The committed OpenAPI spec does not match the code. Run: npm run -w @librechat/api openapi:generate',
+ );
+ process.exit(1);
+ }
+ console.log('The committed OpenAPI spec matches the code.');
+}
+
+if (process.argv.includes('--write')) {
+ write();
+} else if (process.argv.includes('--check')) {
+ check();
+} else {
+ console.error('Pass --write or --check.');
+ process.exit(2);
+}
diff --git a/packages/api/src/openapi/registry.ts b/packages/api/src/openapi/registry.ts
new file mode 100644
index 0000000000..c694aa995c
--- /dev/null
+++ b/packages/api/src/openapi/registry.ts
@@ -0,0 +1,55 @@
+import type { ZodTypeAny } from 'zod';
+import type { EndpointContract, SecurityScheme } from './adapter';
+import {
+ errorMessageResponseSchema,
+ accountDeletionResponseSchema,
+ messageResponseSchema,
+ jsonParseErrorSchema,
+} from './errors';
+import { agentComponentSchemas, agentContracts } from './agents';
+import { skillComponentSchemas, skillContracts } from './skills';
+
+/** The agent and skill management endpoints authenticate with an OIDC access token (bearer). */
+export const securitySchemes: Record<string, SecurityScheme> = {
+ oidcBearer: {
+ type: 'http',
+ scheme: 'bearer',
+ bearerFormat: 'JWT',
+ description: 'An OIDC access token, sent as a bearer token.',
+ },
+};
+
+export const componentSchemas: Record<string, ZodTypeAny> = {
+ ...agentComponentSchemas,
+ ...skillComponentSchemas,
+ ErrorMessage: errorMessageResponseSchema,
+ AccountDeletionConflict: accountDeletionResponseSchema,
+ MessageError: messageResponseSchema,
+ JsonParseError: jsonParseErrorSchema,
+};
+
+/**
+ * Constraints the Zod-to-OpenAPI converter cannot emit, applied to the generated component.
+ * `SkillUpdateRequest`'s object-level `.refine()` (at least one update field) is lost in
+ * conversion; `minProperties: 2` keeps `expectedVersion` plus at least one real field.
+ *
+ * `SkillFileUpdateRequest.content` uses `maxLength`, which counts characters, but `updateFile`
+ * (skills/management.ts) rejects when the UTF-8 buffer exceeds 1 MiB. The converter drops the
+ * field description, so restate the single `content` property here with the byte limit. The
+ * component has only this property, so the whole `properties` object is stated, not clobbered.
+ */
+export const componentSchemaOverrides: Record<string, Record<string, unknown>> = {
+ SkillUpdateRequest: { minProperties: 2 },
+ SkillFileUpdateRequest: {
+ properties: {
+ content: {
+ type: 'string',
+ maxLength: 1024 * 1024,
+ description:
+ 'The file content. The accepted maximum is 1 MiB (1,048,576 bytes) of UTF-8-encoded content. The limit is measured in bytes, not characters, so non-ASCII content reaches it at fewer characters.',
+ },
+ },
+ },
+};
+
+export const contracts: EndpointContract[] = [...agentContracts, ...skillContracts];
diff --git a/packages/api/src/openapi/router.ts b/packages/api/src/openapi/router.ts
new file mode 100644
index 0000000000..ce1e6b0ba0
--- /dev/null
+++ b/packages/api/src/openapi/router.ts
@@ -0,0 +1,108 @@
+import fs from 'fs';
+import path from 'path';
+import express from 'express';
+import { logger, type AppConfig } from '@librechat/data-schemas';
+import type { Request, Response, Router, NextFunction } from 'express';
+import type { GetAppConfigOptions } from '~/app/service';
+
+export interface OpenApiRouterDeps {
+ /**
+ * Resolves the app configuration. The docs gate reads the deployment-wide base config,
+ * so `openapi.enabled` comes from `librechat.yaml` and needs no per-request database read.
+ */
+ getAppConfig: (options: GetAppConfigOptions) => Promise<AppConfig>;
+ /** Absolute path to the bundled Swagger UI assets (from `swagger-ui-dist`). */
+ swaggerAssetsPath: string;
+}
+
+/** The generated spec is copied next to the built bundle, so it ships wherever `dist` ships. */
+const SPEC_PATH = path.join(__dirname, 'agents.openapi.json');
+
+/**
+ * URLs are computed in the browser from the current path, so the docs work whether LibreChat
+ * is served at the origin root or under a base path (e.g. `/chat`) that a proxy strips.
+ */
+const DOCS_HTML = `<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ <title>LibreChat Agents API</title>
+ <script>
+ window.addEventListener('DOMContentLoaded', function () {
+ var apiBase = location.pathname.replace(/\\/+$/, '').replace(/\\/docs$/, '');
+ var link = document.createElement('link');
+ link.rel = 'stylesheet';
+ link.href = apiBase + '/docs/assets/swagger-ui.css';
+ document.head.appendChild(link);
+ var script = document.createElement('script');
+ script.src = apiBase + '/docs/assets/swagger-ui-bundle.js';
+ script.onload = function () {
+ window.ui = SwaggerUIBundle({ url: apiBase + '/openapi.json', dom_id: '#swagger-ui' });
+ };
+ document.body.appendChild(script);
+ });
+ </script>
+ </head>
+ <body>
+ <div id="swagger-ui"></div>
+ </body>
+</html>`;
+
+/** Serves the OpenAPI spec and Swagger UI docs behind the `openapi.enabled` config flag. */
+export function createOpenApiRouter(deps: OpenApiRouterDeps): Router {
+ const router = express.Router();
+ let cachedSpec: string | undefined;
+
+ function readSpec(): string {
+ if (cachedSpec === undefined) {
+ cachedSpec = fs.readFileSync(SPEC_PATH, 'utf8');
+ }
+ return cachedSpec;
+ }
+
+ async function isEnabled(): Promise<boolean> {
+ try {
+ const appConfig = await deps.getAppConfig({ baseOnly: true });
+ return appConfig?.config?.openapi?.enabled === true;
+ } catch (error) {
+ logger.error('[openapi] Failed to read app config', error);
+ return false;
+ }
+ }
+
+ router.get('/openapi.json', async (_req: Request, res: Response): Promise<void> => {
+ if (!(await isEnabled())) {
+ res.status(404).json({ message: 'Not Found' });
+ return;
+ }
+ try {
+ res.type('application/json').send(readSpec());
+ } catch (error) {
+ logger.error('[openapi] Failed to read the OpenAPI spec', error);
+ res.status(500).json({ message: 'Failed to read the OpenAPI spec' });
+ }
+ });
+
+ const serveAssets = express.static(deps.swaggerAssetsPath);
+ router.use(
+ '/docs/assets',
+ async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+ if (!(await isEnabled())) {
+ res.status(404).json({ message: 'Not Found' });
+ return;
+ }
+ serveAssets(req, res, next);
+ },
+ );
+
+ router.get('/docs', async (_req: Request, res: Response): Promise<void> => {
+ if (!(await isEnabled())) {
+ res.status(404).json({ message: 'Not Found' });
+ return;
+ }
+ res.type('html').send(DOCS_HTML);
+ });
+
+ return router;
+}
diff --git a/packages/api/src/openapi/skills.ts b/packages/api/src/openapi/skills.ts
new file mode 100644
index 0000000000..5e2495c052
--- /dev/null
+++ b/packages/api/src/openapi/skills.ts
@@ -0,0 +1,176 @@
+import { z } from 'zod';
+import type { ZodTypeAny } from 'zod';
+import type { EndpointContract } from './adapter';
+import {
+ skillManagementUpdateSchema,
+ skillManagementResponseSchema,
+ skillSummarySchema,
+ skillFileSchema,
+ skillFileContentSchema,
+ skillFileUpdateSchema,
+ skillFrontmatterValueSchema,
+} from '../skills/management';
+import {
+ errorMessageResponseSchema,
+ accountDeletionResponseSchema,
+ messageResponseSchema,
+ jsonParseErrorSchema,
+} from './errors';
+import { agentManagementListSchema, agentManagementErrorSchema } from '../agents/management';
+
+const TAG = 'Skills';
+const SECURITY = ['oidcBearer'];
+
+const skillListResponseSchema = z.object({
+ object: z.literal('list'),
+ data: z.array(skillSummarySchema),
+ first_id: z.string().nullable(),
+ last_id: z.string().nullable(),
+ has_more: z.boolean(),
+ after: z.string().nullable(),
+});
+const skillFileListResponseSchema = z.object({
+ object: z.literal('list'),
+ data: z.array(skillFileSchema),
+});
+const skillFileUpdatedSchema = z.object({
+ relativePath: z.string(),
+ bytes: z.number().int().nonnegative(),
+});
+
+export const skillComponentSchemas: Record<string, ZodTypeAny> = {
+ SkillFrontmatterValue: skillFrontmatterValueSchema,
+ Skill: skillManagementResponseSchema,
+ SkillList: skillListResponseSchema,
+ SkillUpdateRequest: skillManagementUpdateSchema,
+ SkillFile: skillFileSchema,
+ SkillFileList: skillFileListResponseSchema,
+ SkillFileContent: skillFileContentSchema,
+ SkillFileUpdateRequest: skillFileUpdateSchema,
+ SkillFileUpdated: skillFileUpdatedSchema,
+};
+
+const errorResponses = [
+ {
+ status: 400,
+ description: 'Invalid request, or a malformed JSON body',
+ schema: z.union([agentManagementErrorSchema, jsonParseErrorSchema]),
+ },
+ { status: 401, description: 'Authentication failed', schema: errorMessageResponseSchema },
+ {
+ status: 403,
+ description: 'Permission denied, the caller is banned, or the request fails tenant isolation',
+ schema: z.union([
+ agentManagementErrorSchema,
+ messageResponseSchema,
+ errorMessageResponseSchema,
+ ]),
+ },
+ { status: 404, description: 'Not found', schema: agentManagementErrorSchema },
+ {
+ status: 409,
+ description: 'The bound account is being deleted',
+ schema: accountDeletionResponseSchema,
+ },
+ {
+ status: 500,
+ description: 'Internal server error',
+ schema: z.union([agentManagementErrorSchema, errorMessageResponseSchema]),
+ },
+];
+
+export const skillContracts: EndpointContract[] = [
+ {
+ operationId: 'listSkills',
+ method: 'get',
+ path: '/skills',
+ tags: [TAG],
+ summary: 'List skills',
+ security: SECURITY,
+ query: agentManagementListSchema,
+ responses: [
+ { status: 200, description: 'A page of skills', schema: skillListResponseSchema },
+ ...errorResponses,
+ ],
+ },
+ {
+ operationId: 'getSkill',
+ method: 'get',
+ path: '/skills/{id}',
+ tags: [TAG],
+ summary: 'Get a skill',
+ security: SECURITY,
+ pathParams: [{ name: 'id', description: 'The skill id' }],
+ responses: [
+ { status: 200, description: 'The skill', schema: skillManagementResponseSchema },
+ ...errorResponses,
+ ],
+ },
+ {
+ operationId: 'updateSkill',
+ method: 'patch',
+ path: '/skills/{id}',
+ tags: [TAG],
+ summary: 'Update a skill',
+ security: SECURITY,
+ pathParams: [{ name: 'id', description: 'The skill id' }],
+ body: skillManagementUpdateSchema,
+ responses: [
+ { status: 200, description: 'The updated skill', schema: skillManagementResponseSchema },
+ ...errorResponses,
+ {
+ status: 409,
+ description:
+ 'The skill changed since the provided expectedVersion, or the bound account is being deleted',
+ schema: z.union([agentManagementErrorSchema, accountDeletionResponseSchema]),
+ },
+ ],
+ },
+ {
+ operationId: 'listSkillFiles',
+ method: 'get',
+ path: '/skills/{id}/files',
+ tags: [TAG],
+ summary: "List a skill's files",
+ security: SECURITY,
+ pathParams: [{ name: 'id', description: 'The skill id' }],
+ responses: [
+ { status: 200, description: "The skill's files", schema: skillFileListResponseSchema },
+ ...errorResponses,
+ ],
+ },
+ {
+ operationId: 'getSkillFile',
+ method: 'get',
+ path: '/skills/{id}/files/{relativePath}',
+ tags: [TAG],
+ summary: "Get a skill's file",
+ security: SECURITY,
+ pathParams: [
+ { name: 'id', description: 'The skill id' },
+ { name: 'relativePath', description: 'The file path within the skill' },
+ ],
+ responses: [
+ { status: 200, description: 'The file content', schema: skillFileContentSchema },
+ ...errorResponses,
+ ],
+ },
+ {
+ operationId: 'updateSkillFile',
+ method: 'put',
+ path: '/skills/{id}/files/{relativePath}',
+ tags: [TAG],
+ summary: "Create or update a skill's file",
+ security: SECURITY,
+ pathParams: [
+ { name: 'id', description: 'The skill id' },
+ { name: 'relativePath', description: 'The file path within the skill' },
+ ],
+ body: skillFileUpdateSchema,
+ responses: [
+ { status: 200, description: 'The file was written', schema: skillFileUpdatedSchema },
+ ...errorResponses,
+ { status: 429, description: 'Too many file-write requests', schema: messageResponseSchema },
+ ],
+ },
+];
diff --git a/packages/api/src/skills/management.ts b/packages/api/src/skills/management.ts
index d33fec3506..bbc68657b4 100644
--- a/packages/api/src/skills/management.ts
+++ b/packages/api/src/skills/management.ts
@@ -26,14 +26,14 @@ const fields = {
category: z.string().optional(),
alwaysApply: z.boolean().optional(),
};
-const frontmatterValue: z.ZodType<SkillFrontmatterValue> = z.lazy(() =>
+export const skillFrontmatterValueSchema: z.ZodType<SkillFrontmatterValue> = z.lazy(() =>
z.union([
z.string(),
z.number().finite(),
z.boolean(),
z.null(),
- z.array(frontmatterValue),
- z.record(frontmatterValue),
+ z.array(skillFrontmatterValueSchema),
+ z.record(skillFrontmatterValueSchema),
]),
);
export type SkillManagementUpdate = TUpdateSkillPayload & { expectedVersion: number };
@@ -46,13 +46,13 @@ export const skillManagementUpdateSchema: z.ZodType<SkillManagementUpdate> = z
category: fields.category,
alwaysApply: fields.alwaysApply,
body: z.string().optional(),
- frontmatter: z.record(frontmatterValue).optional(),
+ frontmatter: z.record(skillFrontmatterValueSchema).optional(),
expectedVersion: z.number().int().positive(),
})
.strict()
.refine((value) => Object.keys(value).length > 1, 'At least one update field is required');
-const summarySchema = z.object({
+export const skillSummarySchema: z.AnyZodObject = z.object({
...fields,
id: idSchema,
version: z.number().int().positive(),
@@ -81,22 +81,32 @@ export type SkillManagementResponse = Pick<
| 'frontmatter'
> & { id: string };
-export const skillManagementResponseSchema: z.ZodType<SkillManagementResponse> =
- summarySchema.extend({
- body: z.string(),
- frontmatter: z.record(frontmatterValue).optional(),
- });
-const fileSchema = z.object({
+export const skillManagementResponseSchema: z.ZodType<SkillManagementResponse> = z.object({
+ ...fields,
+ id: idSchema,
+ version: z.number().int().positive(),
+ fileCount: z.number().int().nonnegative(),
+ disableModelInvocation: z.boolean().optional(),
+ userInvocable: z.boolean().optional(),
+ allowedTools: z.array(z.string()).optional(),
+ createdAt: z.string().datetime(),
+ updatedAt: z.string().datetime(),
+ body: z.string(),
+ frontmatter: z.record(skillFrontmatterValueSchema).optional(),
+});
+export const skillFileSchema: z.AnyZodObject = z.object({
relativePath: z.string(),
filename: z.string(),
mimeType: z.string(),
bytes: z.number().int().nonnegative(),
});
-const fileContentSchema = fileSchema.extend({
+export const skillFileContentSchema: z.AnyZodObject = skillFileSchema.extend({
content: z.string().optional(),
isBinary: z.boolean(),
});
-const fileUpdateSchema = z.object({ content: z.string().max(1024 * 1024) }).strict();
+export const skillFileUpdateSchema: z.AnyZodObject = z
+ .object({ content: z.string().max(1024 * 1024) })
+ .strict();
const listSchema = agentManagementListSchema;
type ManagementRequest = Request &
@@ -127,7 +137,7 @@ export interface SkillManagementDeps {
function projectSkill(body: unknown, detail: boolean): object {
const source = z.object({ _id: idSchema }).passthrough().parse(body);
- return (detail ? skillManagementResponseSchema : summarySchema).parse({
+ return (detail ? skillManagementResponseSchema : skillSummarySchema).parse({
...source,
id: source._id,
});
@@ -323,17 +333,17 @@ export function createSkillManagementHandlers(
listFiles: wrap(PermissionBits.VIEW, (req, res) =>
runHandler(req, res, deps.handlers.listFiles, (body) => ({
object: 'list',
- data: z.object({ files: z.array(fileSchema) }).parse(body).files,
+ data: z.object({ files: z.array(skillFileSchema) }).parse(body).files,
})),
),
getFile: wrap(PermissionBits.VIEW, async (req, res) => {
if (Object.keys(req.query).length > 0) return sendError(res, 'invalid_request');
return runHandler(req, res, deps.handlers.downloadFile, (body) =>
- fileContentSchema.parse(body),
+ skillFileContentSchema.parse(body),
);
}),
updateFile: wrap(PermissionBits.EDIT, async (req, res) => {
- const parsed = fileUpdateSchema.safeParse(req.body);
+ const parsed = skillFileUpdateSchema.safeParse(req.body);
if (!parsed.success) return sendError(res, 'invalid_request', parsed.error);
const relativePath = resolveSkillFilePathParam(req.params.relativePath);
if (relativePath == null || validateRelativePath(relativePath).length > 0)
diff --git a/packages/api/tsconfig.openapi.json b/packages/api/tsconfig.openapi.json
new file mode 100644
index 0000000000..c9abcb3dac
--- /dev/null
+++ b/packages/api/tsconfig.openapi.json
@@ -0,0 +1,16 @@
+{
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "baseUrl": ".",
+ "module": "commonjs",
+ "moduleResolution": "node"
+ },
+ "ts-node": {
+ "esm": false,
+ "transpileOnly": true,
+ "compilerOptions": {
+ "module": "commonjs",
+ "moduleResolution": "node"
+ }
+ }
+}
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 151c66ba3b..3ad4c89ff5 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -2989,6 +2989,12 @@ export const configSchema = z.object({
message: 'At least one `endpoints` field must be provided.',
})
.optional(),
+ /** Serve the OpenAPI spec and docs for the public Agents API. Off by default. */
+ openapi: z
+ .object({
+ enabled: z.boolean().optional(),
+ })
+ .optional(),
});
/**